Feat : add a Hub class

CHANGELOG.md

@@ -20,6 +20,7 @@
 - new static API : Sentry.init(), Sentry.captureEvent() #108
 - expect a sdkName based on the test platform #105
 - Added Scope and Breadcrumb ring buffer #109
+- Added Hub ring buffer #113
 
 # `package:sentry` changelog
 

dart/example/main.dart

@@ -23,29 +23,21 @@ Future<void> main(List<String> rawArgs) async {
   print('\nReporting a complete event example: ');
 
   // Sends a full Sentry event payload to show the different parts of the UI.
-  final response = await Sentry.captureEvent(event);
+  final sentryId = await Sentry.captureEvent(event);
 
-  if (response.isSuccessful) {
-    print('SUCCESS\nid: ${response.eventId}');
-  } else {
-    print('FAILURE: ${response.error}');
-  }
+  print('SentryId : ${sentryId.id}');
 
   try {
     await foo();
   } catch (error, stackTrace) {
     print('\nReporting the following stack trace: ');
     print(stackTrace);
-    final response = await Sentry.captureException(
+    final sentryId = await Sentry.captureException(
       error,
       stackTrace: stackTrace,
     );
 
-    if (response.isSuccessful) {
-      print('SUCCESS\nid: ${response.eventId}');
-    } else {
-      print('FAILURE: ${response.error}');
-    }
+    print('SentryId : ${sentryId.id}');
   } finally {
     await Sentry.close();
   }

dart/lib/src/client.dart

@@ -3,6 +3,7 @@ import 'dart:convert';
 
 import 'package:http/http.dart';
 import 'package:meta/meta.dart';
+import 'package:sentry/sentry.dart';
 
 import 'client_stub.dart'
     if (dart.library.html) 'browser_client.dart'
@@ -136,9 +137,10 @@ abstract class SentryClient {
   }
 
   /// Reports an [event] to Sentry.io.
-  Future<SentryResponse> captureEvent({
-    @required Event event,
+  Future<SentryId> captureEvent(
+    Event event, {
     StackFrameFilter stackFrameFilter,
+    Scope scope,
   }) async {
     final now = _clock();
     var authHeader = 'Sentry sentry_version=6, sentry_client=$clientId, '
@@ -183,27 +185,33 @@ abstract class SentryClient {
     );
 
     if (response.statusCode != 200) {
-      var errorMessage = 'Sentry.io responded with HTTP ${response.statusCode}';
+      /*var errorMessage = 'Sentry.io responded with HTTP ${response.statusCode}';
       if (response.headers['x-sentry-error'] != null) {
         errorMessage += ': ${response.headers['x-sentry-error']}';
-      }
-      return SentryResponse.failure(errorMessage);
+      }*/
+      return SentryId.empty();
     }
 
-    final eventId = '${json.decode(response.body)['id']}';
-    return SentryResponse.success(eventId: eventId);
+    final eventId = json.decode(response.body)['id'];
+    return eventId != null ? SentryId(eventId) : SentryId.empty();
   }
 
-  /// Reports the [exception] and optionally its [stackTrace] to Sentry.io.
-  Future<SentryResponse> captureException({
-    @required dynamic exception,
-    dynamic stackTrace,
-  }) {
+  /// Reports the [throwable] and optionally its [stackTrace] to Sentry.io.
+  Future<SentryId> captureException(dynamic throwable, {dynamic stackTrace}) {
     final event = Event(
-      exception: exception,
+      exception: throwable,
       stackTrace: stackTrace,
     );
-    return captureEvent(event: event);
+    return captureEvent(event);
+  }
+
+  /// Reports the [message]
+  Future<SentryId> captureMessage(
+    Message message, {
+    SeverityLevel level = SeverityLevel.info,
+  }) {
+    final event = Event(message: message, level: level);
+    return captureEvent(event);
   }
 
   Future<void> close() async {

dart/lib/src/hub.dart

@@ -0,0 +1,280 @@
+import 'dart:async';
+import 'dart:collection';
+
+import 'client.dart';
+import 'noop_client.dart';
+import 'protocol.dart';
+import 'scope.dart';
+import 'sentry_options.dart';
+
+typedef ScopeCallback = void Function(Scope);
+
+/// SDK API contract which combines a client and scope management
+class Hub {
+  static SentryClient _getClient({SentryOptions fromOptions}) {
+    return SentryClient(
+      dsn: fromOptions.dsn,
+      environmentAttributes: fromOptions.environmentAttributes,
+      compressPayload: fromOptions.compressPayload,
+      httpClient: fromOptions.httpClient,
+      clock: fromOptions.clock,
+      uuidGenerator: fromOptions.uuidGenerator,
+    );
+  }
+
+  final ListQueue<_StackItem> _stack;
+
+  final SentryOptions _options;
+
+  factory Hub(SentryOptions options) {
+    _validateOptions(options);
+
+    return Hub._(options);
+  }
+
+  Hub._(SentryOptions options)
+      : _options = options,
+        _stack = ListQueue() {
+    _stack.add(_StackItem(_getClient(fromOptions: options), Scope(_options)));
+    _isEnabled = true;
+  }
+
+  static void _validateOptions(SentryOptions options) {
+    if (options == null) {
+      throw ArgumentError.notNull('options');
+    }
+
+    if (options.dsn == null) {
+      throw ArgumentError.notNull('options.dsn');
+    }
+  }
+
+  bool _isEnabled = false;
+
+  /// Check if the Hub is enabled/active.
+  bool get isEnabled => _isEnabled;
+
+  SentryId _lastEventId;
+
+  /// Last event id recorded in the current scope
+  SentryId get lastEventId => _lastEventId;
+
+  /// Captures the event.
+  Future<SentryId> captureEvent(Event event) async {
+    var sentryId = SentryId.empty();
+
+    if (!_isEnabled) {
+      _options.logger(
+        SeverityLevel.warning,
+        "Instance is disabled and this 'captureEvent' call is a no-op.",
+      );
+    } else if (event == null) {
+      _options.logger(
+        SeverityLevel.warning,
+        'captureEvent called with null parameter.',
+      );
+    } else {
+      final item = _stack.first;
+      if (item != null) {
+        try {
+          sentryId = await item.client.captureEvent(event, scope: item.scope);
+        } catch (err) {
+          /* TODO add Event.id */
+          _options.logger(
+            SeverityLevel.error,
+            'Error while capturing event with id: ${event}',
+          );
+        }
+      } else {
+        _options.logger(
+          SeverityLevel.fatal,
+          'Stack peek was null when captureEvent',
+        );
+      }
+    }
+    _lastEventId = sentryId;
+    return sentryId;
+  }
+
+  /// Captures the exception
+  Future<SentryId> captureException(
+    dynamic throwable, {
+    dynamic stackTrace,
+  }) async {
+    var sentryId = SentryId.empty();
+
+    if (!_isEnabled) {
+      _options.logger(
+        SeverityLevel.warning,
+        "Instance is disabled and this 'captureException' call is a no-op.",
+      );
+    } else if (throwable == null) {
+      _options.logger(
+        SeverityLevel.warning,
+        'captureException called with null parameter.',
+      );
+    } else {
+      final item = _stack.first;
+      if (item != null) {
+        try {
+          // TODO pass the scope
+          sentryId = await item.client.captureException(
+            throwable,
+            stackTrace: stackTrace,
+          );
+        } catch (err) {
+          _options.logger(
+            SeverityLevel.error,
+            'Error while capturing exception : ${throwable}',
+          );
+        }
+      } else {
+        _options.logger(
+          SeverityLevel.fatal,
+          'Stack peek was null when captureException',
+        );
+      }
+    }
+    _lastEventId = sentryId;
+    return sentryId;
+  }
+
+  /// Captures the message.
+  Future<SentryId> captureMessage(
+    Message message, {
+    SeverityLevel level = SeverityLevel.info,
+  }) async {
+    var sentryId = SentryId.empty();
+
+    if (!_isEnabled) {
+      _options.logger(
+        SeverityLevel.warning,
+        "Instance is disabled and this 'captureMessage' call is a no-op.",
+      );
+    } else if (message == null) {
+      _options.logger(
+        SeverityLevel.warning,
+        'captureMessage called with null parameter.',
+      );
+    } else {
+      final item = _stack.first;
+      if (item != null) {
+        try {
+          // TODO pass the scope
+          sentryId = await item.client.captureMessage(message, level: level);
+        } catch (err) {
+          _options.logger(
+            SeverityLevel.error,
+            'Error while capturing message with id: ${message}',
+          );
+        }
+      } else {
+        _options.logger(
+          SeverityLevel.fatal,
+          'Stack peek was null when captureMessage',
+        );
+      }
+    }
+    _lastEventId = sentryId;
+    return sentryId;
+  }
+
+  /// Binds a different client to the hub
+  void bindClient(SentryClient client) {
+    if (!_isEnabled) {
+      _options.logger(SeverityLevel.warning,
+          "Instance is disabled and this 'bindClient' call is a no-op.");
+    } else {
+      final item = _stack.first;
+      if (item != null) {
+        if (client != null) {
+          _options.logger(SeverityLevel.debug, 'New client bound to scope.');
+          item.client = client;
+        } else {
+          _options.logger(SeverityLevel.debug, 'NoOp client bound to scope.');
+          item.client = NoOpSentryClient();
+        }
+      } else {
+        _options.logger(
+          SeverityLevel.fatal,
+          'Stack peek was null when bindClient',
+        );
+      }
+    }
+  }
+
+  /// Clones the Hub
+  Hub clone() {
+    if (!_isEnabled) {
+      _options..logger(SeverityLevel.warning, 'Disabled Hub cloned.');
+    }
+    final clone = Hub(_options);
+    for (final item in _stack) {
+      clone._stack.add(_StackItem(item.client, item.scope.clone()));
+    }
+    return clone;
+  }
+
+  /// Flushes out the queue for up to timeout seconds and disable the Hub.
+  void close() {
+    if (!_isEnabled) {
+      _options.logger(
+        SeverityLevel.warning,
+        "Instance is disabled and this 'close' call is a no-op.",
+      );
+    } else {
+      final item = _stack.first;
+      if (item != null) {
+        try {
+          item.client.close();
+        } catch (err) {
+          _options.logger(
+            SeverityLevel.error,
+            'Error while closing the Hub.',
+          );
+        }
+      } else {
+        _options.logger(
+          SeverityLevel.fatal,
+          'Stack peek was NULL when closing Hub',
+        );
+      }
+      _isEnabled = false;
+    }
+  }
+
+  /// Configures the scope through the callback.
+  void configureScope(ScopeCallback callback) {
+    if (!_isEnabled) {
+      _options.logger(
+        SeverityLevel.warning,
+        "Instance is disabled and this 'configureScope' call is a no-op.",
+      );
+    } else {
+      final item = _stack.first;
+      if (item != null) {
+        try {
+          callback(item.scope);
+        } catch (err) {
+          _options.logger(
+            SeverityLevel.error,
+            "Error in the 'configureScope' callback.",
+          );
+        }
+      } else {
+        _options.logger(
+          SeverityLevel.fatal,
+          'Stack peek was NULL when configureScope',
+        );
+      }
+    }
+  }
+}
+
+class _StackItem {
+  SentryClient client;
+
+  final Scope scope;
+
+  _StackItem(this.client, this.scope);
+}