feat: Add onCrashedLastRun

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## unreleased
 
+- feat: Add onCrashedLastRun #808
 - feat: Add SentrySdkInfo to SentryOptions #859
 
 ## 6.0.9

Sources/Sentry/Public/SentryDefines.h

@@ -48,6 +48,11 @@ typedef SentryBreadcrumb *_Nullable (^SentryBeforeBreadcrumbCallback)(
  */
 typedef SentryEvent *_Nullable (^SentryBeforeSendEventCallback)(SentryEvent *_Nonnull event);
 
+/**
+ * A callback to be notified when the last program execution terminated with a crash.
+ */
+typedef void (^SentryOnCrashedLastRunCallback)(SentryEvent *_Nonnull event);
+
 /**
  * Block can be used to determine if an event should be queued and stored
  * locally. It will be tried to send again after next successful send. Note that

Sources/Sentry/Public/SentryOptions.h

@@ -79,6 +79,17 @@ NS_SWIFT_NAME(Options)
  */
 @property (nonatomic, copy) SentryBeforeBreadcrumbCallback _Nullable beforeBreadcrumb;
 
+/**
+ * This gets called shortly after the initialization of the SDK when the last program execution
+ * terminated with a crash. It is not guaranteed that this is called on the main thread.
+ *
+ * @discussion This callback is only executed once during the entire run of the program to avoid
+ * multiple callbacks if there are multiple crash events to send. This can happen when the program
+ * terminates with a crash before the SDK can send the crash event. You can look into beforeSend if
+ * you prefer a callback for every event.
+ */
+@property (nonatomic, copy) SentryOnCrashedLastRunCallback _Nullable onCrashedLastRun;
+
 /**
  * Array of integrations to install.
  */

Sources/Sentry/SentryClient.m

@@ -1,5 +1,6 @@
 #import "SentryClient.h"
 #import "NSDictionary+SentrySanitize.h"
+#import "SentryCrashAdapter.h"
 #import "SentryCrashDefaultBinaryImageProvider.h"
 #import "SentryCrashDefaultMachineContextWrapper.h"
 #import "SentryDebugMetaBuilder.h"
@@ -14,9 +15,12 @@
 #import "SentryId.h"
 #import "SentryInstallation.h"
 #import "SentryLog.h"
+#import "SentryMechanism.h"
 #import "SentryMessage.h"
 #import "SentryMeta.h"
 #import "SentryOptions.h"
+#import "SentrySDK+Private.h"
+#import "SentrySDK.h"
 #import "SentryScope.h"
 #import "SentryStacktraceBuilder.h"
 #import "SentryThreadInspector.h"
@@ -38,6 +42,7 @@
 @property (nonatomic, strong) SentryFileManager *fileManager;
 @property (nonatomic, strong) SentryDebugMetaBuilder *debugMetaBuilder;
 @property (nonatomic, strong) SentryThreadInspector *threadInspector;
+@property (nonatomic, strong) SentryCrashAdapter *crashAdapter;
 
 @end
 
@@ -79,6 +84,8 @@ - (_Nullable instancetype)initWithOptions:(SentryOptions *)options
 
         self.transport = [SentryTransportFactory initTransport:self.options
                                              sentryFileManager:self.fileManager];
+
+        self.crashAdapter = [[SentryCrashAdapter alloc] init];
     }
     return self;
 }
@@ -87,11 +94,13 @@ - (_Nullable instancetype)initWithOptions:(SentryOptions *)options
 - (instancetype)initWithOptions:(SentryOptions *)options
                    andTransport:(id<SentryTransport>)transport
                  andFileManager:(SentryFileManager *)fileManager
+                andCrashAdapter:(SentryCrashAdapter *)crashAdapter
 {
     self = [self initWithOptions:options];
 
     self.transport = transport;
     self.fileManager = fileManager;
+    self.crashAdapter = crashAdapter;
 
     return self;
 }
@@ -366,6 +375,8 @@ - (SentryEvent *_Nullable)prepareEvent:(SentryEvent *)event
         event = self.options.beforeSend(event);
     }
 
+    [self callOnCrashedLastRun:event];
+
     return event;
 }
 
@@ -422,6 +433,35 @@ - (void)setUserIdIfNoUserSet:(SentryEvent *)event
     }
 }
 
+/**
+ * Calls onCrashedLastRun if the execution terminated with a crash.
+ */
+- (void)callOnCrashedLastRun:(SentryEvent *)event
+{
+    if (nil != self.options.onCrashedLastRun && self.crashAdapter.crashedLastLaunch
+        && !SentrySDK.crashedLastRunCalled && nil != event.exceptions) {
+
+        NSPredicate *unhandledExpeptions = [NSPredicate predicateWithBlock:^BOOL(
+            id _Nullable object, NSDictionary<NSString *, id> *_Nullable bindings) {
+            SentryException *exception = object;
+            return nil != exception.mechanism && nil != exception.mechanism.handled
+                && ![exception.mechanism.handled boolValue];
+        }];
+
+        // We only want to filter the array if the above conditions are true to avoid unecessary
+        // work
+        BOOL eventContainsUnhandledExceptions =
+            [event.exceptions filteredArrayUsingPredicate:unhandledExpeptions].count > 0;
+
+        if (eventContainsUnhandledExceptions) {
+            // We only want to call the callback once. It can occur that multiple crash events are
+            // about to be sent.
+            SentrySDK.crashedLastRunCalled = YES;
+            self.options.onCrashedLastRun(event);
+        }
+    }
+}
+
 @end
 
 NS_ASSUME_NONNULL_END

Sources/Sentry/SentryOptions.m

@@ -128,6 +128,10 @@ - (void)validateOptions:(NSDictionary<NSString *, id> *)options
         self.beforeBreadcrumb = options[@"beforeBreadcrumb"];
     }
 
+    if (nil != options[@"onCrashedLastRun"]) {
+        self.onCrashedLastRun = options[@"onCrashedLastRun"];
+    }
+
     if (nil != options[@"integrations"]) {
         self.integrations = options[@"integrations"];
     }

Sources/Sentry/SentrySDK.m

@@ -23,6 +23,7 @@
 @implementation SentrySDK
 
 static SentryHub *currentHub;
+static BOOL crashedLastRunCalled;
 
 @dynamic logLevel;
 
@@ -43,6 +44,16 @@ + (void)setCurrentHub:(SentryHub *)hub
     }
 }
 
++ (BOOL)crashedLastRunCalled
+{
+    return crashedLastRunCalled;
+}
+
++ (void)setCrashedLastRunCalled:(BOOL)value
+{
+    crashedLastRunCalled = value;
+}
+
 + (void)startWithOptions:(NSDictionary<NSString *, id> *)optionsDict
 {
     NSError *error = nil;

Sources/Sentry/include/SentrySDK+Private.h

@@ -8,6 +8,11 @@ NS_ASSUME_NONNULL_BEGIN
 
 + (void)captureCrashEvent:(SentryEvent *)event;
 
+/**
+ * SDK private field to store the state if onCrashedLastRun was called.
+ */
+@property (nonatomic, class) BOOL crashedLastRunCalled;
+
 @end
 
 NS_ASSUME_NONNULL_END

Tests/SentryTests/SentryClient+TestInit.h

@@ -1,14 +1,17 @@
 #import "SentryTransport.h"
 #import <Sentry/Sentry.h>
 
+@class SentryCrashAdapter;
+
 NS_ASSUME_NONNULL_BEGIN
 
 /** Expose the internal test init for testing. */
 @interface SentryClient (TestInit)
 
 - (instancetype)initWithOptions:(SentryOptions *)options
                    andTransport:(id<SentryTransport>)transport
-                 andFileManager:(SentryFileManager *)fileManager;
+                 andFileManager:(SentryFileManager *)fileManager
+                andCrashAdapter:(SentryCrashAdapter *)crashAdapter;
 
 @end
 

Tests/SentryTests/SentryClientTests.swift

@@ -25,6 +25,8 @@ class SentryClientTest: XCTestCase {
         let user: User
         let fileManager: SentryFileManager
 
+        let crashAdapter = TestSentryCrashWrapper()
+
         init() {
             session = SentrySession(releaseName: "release")
             session.incrementErrors()
@@ -48,7 +50,7 @@ class SentryClientTest: XCTestCase {
                 ])
                 configureOptions(options)
 
-                client = Client(options: options, andTransport: transport, andFileManager: fileManager)
+                client = Client(options: options, andTransport: transport, andFileManager: fileManager, andCrashAdapter: crashAdapter)
             } catch {
                 XCTFail("Options could not be created")
             }
@@ -76,6 +78,16 @@ class SentryClientTest: XCTestCase {
                 return scope
             }
         }
+
+        var eventWithCrash: Event {
+            let event = TestData.event
+            let exception = Exception(value: "value", type: "type")
+            let mechanism = Mechanism(type: "mechanism")
+            mechanism.handled = false
+            exception.mechanism = mechanism
+            event.exceptions = [exception]
+            return event
+        }
     }
 
     private let error = NSError(domain: "domain", code: -20, userInfo: [NSLocalizedDescriptionKey: "Object does not exist"])
@@ -90,6 +102,11 @@ class SentryClientTest: XCTestCase {
         fixture.fileManager.deleteAllEnvelopes()
     }
 
+    override func tearDown() {
+        super.tearDown()
+        SentrySDK.crashedLastRunCalled = false
+    }
+
     func testCaptureMessage() {
         let eventId = fixture.getSut().capture(message: fixture.messageAsString)
 
@@ -615,6 +632,44 @@ class SentryClientTest: XCTestCase {
         XCTAssertEqual(1, fixture.fileManager.getAllEnvelopes().count)
     }
 
+    func testOnCrashedLastRun_WithTwoCrashes_OnlyInvoceOnce() {
+        let event = fixture.eventWithCrash
+
+        var onCrashedLastRunCalled = false
+        let client = fixture.getSut(configureOptions: { options in
+            options.onCrashedLastRun = { crashEvent in
+                onCrashedLastRunCalled = true
+                XCTAssertEqual(event.eventId, crashEvent.eventId)
+            }
+        })
+        fixture.crashAdapter.internalCrashedLastLaunch = true
+
+        client.capture(event: event)
+        client.capture(event: fixture.eventWithCrash)
+
+        XCTAssertTrue(onCrashedLastRunCalled)
+    }
+
+    func testOnCrashedLastRun_WithHandledException() {
+        var onCrashedLastRunCalled = false
+        let client = fixture.getSut(configureOptions: { options in
+            options.onCrashedLastRun = { _ in
+                onCrashedLastRunCalled = true
+            }
+        })
+        fixture.crashAdapter.internalCrashedLastLaunch = true
+
+        client.capture(event: TestData.event)
+
+        XCTAssertFalse(onCrashedLastRunCalled)
+    }
+
+    func testOnCrashedLastRun_WithOutCallback_DoesNothing() {
+        let client = fixture.getSut()
+        fixture.crashAdapter.internalCrashedLastLaunch = true
+        client.capture(event: fixture.eventWithCrash)
+    }
+
     private func givenEventWithDebugMeta() -> Event {
         let event = Event(level: SentryLevel.fatal)
         let debugMeta = DebugMeta()

Tests/SentryTests/SentryOptionsTest.m

@@ -204,6 +204,28 @@ - (void)testDefaultBeforeBreadcrumb
     XCTAssertNil(options.beforeBreadcrumb);
 }
 
+- (void)testOnCrashedLastRun
+{
+    __block BOOL onCrashedLastRunCalled = NO;
+    void (^callback)(SentryEvent *event) = ^(SentryEvent *event) {
+        onCrashedLastRunCalled = YES;
+        XCTAssertNotNil(event);
+    };
+    SentryOptions *options = [self getValidOptions:@{ @"onCrashedLastRun" : callback }];
+
+    options.onCrashedLastRun([[SentryEvent alloc] init]);
+
+    XCTAssertEqual(callback, options.onCrashedLastRun);
+    XCTAssertTrue(onCrashedLastRunCalled);
+}
+
+- (void)testDefaultOnCrashedLastRun
+{
+    SentryOptions *options = [self getValidOptions:@{}];
+
+    XCTAssertNil(options.onCrashedLastRun);
+}
+
 - (void)testIntegrations
 {
     NSArray<NSString *> *integrations = @[ @"integration1", @"integration2" ];