refactor(core): Hand out AutoCloseable token from re-entrancy guard

Replace the manual enter()/finally-exit() pattern at every callback site
with an ISentryLifecycleToken returned from enter(), used via
try-with-resources. This removes nine copies of the finally boilerplate
and the risk of forgetting the exit() call.

The depth counter stays as the guard's state model - the token's close()
just decrements it - so the nesting correctness guarantee is unchanged.
The token is a shared static singleton, so no allocation happens per
callback, matching the AutoClosableReentrantLock idiom already in the
codebase.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: runningcode

sentry/src/main/java/io/sentry/Scope.java

@@ -465,8 +465,7 @@ public Queue<Breadcrumb> getBreadcrumbs() {
       final @NotNull SentryOptions.BeforeBreadcrumbCallback callback,
       @NotNull Breadcrumb breadcrumb,
       final @NotNull Hint hint) {
-    try {
-      SentryCallbackReentrancyGuard.enter();
+    try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
       breadcrumb = callback.execute(breadcrumb, hint);
     } catch (Throwable e) {
       options
@@ -479,8 +478,6 @@ public Queue<Breadcrumb> getBreadcrumbs() {
       if (e.getMessage() != null) {
         breadcrumb.setData("sentry:message", e.getMessage());
       }
-    } finally {
-      SentryCallbackReentrancyGuard.exit();
     }
     return breadcrumb;
   }

sentry/src/main/java/io/sentry/SentryClient.java

@@ -245,8 +245,7 @@ private boolean shouldApplyScopeData(final @NotNull CheckIn event, final @NotNul
       final SentryReplayOptions.BeforeErrorSamplingCallback beforeErrorSampling =
           options.getSessionReplay().getBeforeErrorSampling();
       if (beforeErrorSampling != null) {
-        try {
-          SentryCallbackReentrancyGuard.enter();
+        try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
           shouldCaptureReplay = beforeErrorSampling.execute(event, hint);
         } catch (Throwable e) {
           options
@@ -256,8 +255,6 @@ private boolean shouldApplyScopeData(final @NotNull CheckIn event, final @NotNul
                   "The beforeErrorSampling callback threw an exception. Proceeding with replay capture.",
                   e);
           shouldCaptureReplay = true;
-        } finally {
-          SentryCallbackReentrancyGuard.exit();
         }
       }
       if (shouldCaptureReplay) {
@@ -961,15 +958,12 @@ public void captureSession(final @NotNull Session session, final @Nullable Hint
     final @Nullable SentryOptions.BeforeEnvelopeCallback beforeEnvelopeCallback =
         options.getBeforeEnvelopeCallback();
     if (beforeEnvelopeCallback != null) {
-      try {
-        SentryCallbackReentrancyGuard.enter();
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         beforeEnvelopeCallback.execute(envelope, hint);
       } catch (Throwable e) {
         options
             .getLogger()
             .log(SentryLevel.ERROR, "The BeforeEnvelope callback threw an exception.", e);
-      } finally {
-        SentryCallbackReentrancyGuard.exit();
       }
     }
 
@@ -1672,8 +1666,7 @@ private void sortBreadcrumbsByDate(
       @NotNull SentryEvent event, final @NotNull Hint hint) {
     final SentryOptions.BeforeSendCallback beforeSend = options.getBeforeSend();
     if (beforeSend != null) {
-      try {
-        SentryCallbackReentrancyGuard.enter();
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSend.execute(event, hint);
       } catch (Throwable e) {
         options
@@ -1685,8 +1678,6 @@ private void sortBreadcrumbsByDate(
 
         // drop event in case of an error in beforeSend due to PII concerns
         event = null;
-      } finally {
-        SentryCallbackReentrancyGuard.exit();
       }
     }
     return event;
@@ -1697,8 +1688,7 @@ private void sortBreadcrumbsByDate(
     final SentryOptions.BeforeSendTransactionCallback beforeSendTransaction =
         options.getBeforeSendTransaction();
     if (beforeSendTransaction != null) {
-      try {
-        SentryCallbackReentrancyGuard.enter();
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         transaction = beforeSendTransaction.execute(transaction, hint);
       } catch (Throwable e) {
         options
@@ -1710,8 +1700,6 @@ private void sortBreadcrumbsByDate(
 
         // drop transaction in case of an error in beforeSend due to PII concerns
         transaction = null;
-      } finally {
-        SentryCallbackReentrancyGuard.exit();
       }
     }
     return transaction;
@@ -1721,8 +1709,7 @@ private void sortBreadcrumbsByDate(
       @NotNull SentryEvent event, final @NotNull Hint hint) {
     final SentryOptions.BeforeSendCallback beforeSendFeedback = options.getBeforeSendFeedback();
     if (beforeSendFeedback != null) {
-      try {
-        SentryCallbackReentrancyGuard.enter();
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSendFeedback.execute(event, hint);
       } catch (Throwable e) {
         options
@@ -1731,8 +1718,6 @@ private void sortBreadcrumbsByDate(
 
         // drop feedback in case of an error in beforeSend due to PII concerns
         event = null;
-      } finally {
-        SentryCallbackReentrancyGuard.exit();
       }
     }
     return event;
@@ -1742,8 +1727,7 @@ private void sortBreadcrumbsByDate(
       @NotNull SentryReplayEvent event, final @NotNull Hint hint) {
     final SentryOptions.BeforeSendReplayCallback beforeSendReplay = options.getBeforeSendReplay();
     if (beforeSendReplay != null) {
-      try {
-        SentryCallbackReentrancyGuard.enter();
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSendReplay.execute(event, hint);
       } catch (Throwable e) {
         options
@@ -1755,8 +1739,6 @@ private void sortBreadcrumbsByDate(
 
         // drop event in case of an error in beforeSend due to PII concerns
         event = null;
-      } finally {
-        SentryCallbackReentrancyGuard.exit();
       }
     }
     return event;
@@ -1766,8 +1748,7 @@ private void sortBreadcrumbsByDate(
     final SentryOptions.Logs.BeforeSendLogCallback beforeSendLog =
         options.getLogs().getBeforeSend();
     if (beforeSendLog != null) {
-      try {
-        SentryCallbackReentrancyGuard.enter();
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSendLog.execute(event);
       } catch (Throwable e) {
         options
@@ -1779,8 +1760,6 @@ private void sortBreadcrumbsByDate(
 
         // drop event in case of an error in beforeSendLog due to PII concerns
         event = null;
-      } finally {
-        SentryCallbackReentrancyGuard.exit();
       }
     }
     return event;
@@ -1791,8 +1770,7 @@ private void sortBreadcrumbsByDate(
     final SentryOptions.Metrics.BeforeSendMetricCallback beforeSendMetric =
         options.getMetrics().getBeforeSend();
     if (beforeSendMetric != null) {
-      try {
-        SentryCallbackReentrancyGuard.enter();
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSendMetric.execute(event, hint);
       } catch (Throwable e) {
         options
@@ -1804,8 +1782,6 @@ private void sortBreadcrumbsByDate(
 
         // drop event in case of an error in beforeSendMetric due to PII concerns
         event = null;
-      } finally {
-        SentryCallbackReentrancyGuard.exit();
       }
     }
     return event;

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

@@ -1,6 +1,8 @@
 package io.sentry.util;
 
+import io.sentry.ISentryLifecycleToken;
 import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
@@ -22,12 +24,18 @@
  * clear it while an outer callback is still running. Capture entry points drop while a callback is
  * active, so callbacks should never nest — but a capture path lacking an entry check must not
  * silently disarm the guard for the rest of the outer callback.
+ *
+ * <p>{@link #enter()} returns an {@link ISentryLifecycleToken} so callers can use try-with-resources
+ * instead of a manual {@code finally exit()}. The token is a shared singleton (its {@code close()}
+ * just decrements the counter), so no allocation happens per callback.
  */
 @ApiStatus.Internal
 public final class SentryCallbackReentrancyGuard {
 
   private static final ThreadLocal<Integer> depth = new ThreadLocal<>();
 
+  private static final ISentryLifecycleToken TOKEN = SentryCallbackReentrancyGuard::exit;
+
   private SentryCallbackReentrancyGuard() {}
 
   /** Whether a user callback is currently executing on this thread. */
@@ -36,14 +44,17 @@ public static boolean isActive() {
     return current != null && current > 0;
   }
 
-  /** Marks that a user callback is starting to execute on this thread. */
-  public static void enter() {
+  /**
+   * Marks that a user callback is starting to execute on this thread. Close the returned token (via
+   * try-with-resources) once the callback returns.
+   */
+  public static @NotNull ISentryLifecycleToken enter() {
     final @Nullable Integer current = depth.get();
     depth.set(current == null ? 1 : current + 1);
+    return TOKEN;
   }
 
-  /** Marks that the user callback finished executing on this thread. */
-  public static void exit() {
+  private static void exit() {
     final @Nullable Integer current = depth.get();
     if (current == null || current <= 1) {
       depth.remove();