add object browser support

Author: Ivan Dlugos

objectbox/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## latest
 
 * Add `Query.findUnique()` to find a single object matching the query.
+* Add data `Browser`, see [docs](https://docs.objectbox.io/data-browser) for more details. 
 
 ## 1.1.1 (2021-07-09)
 

objectbox/lib/objectbox.dart

@@ -6,6 +6,7 @@ library objectbox;
 
 export 'src/annotations.dart';
 export 'src/box.dart' show Box, PutMode;
+export 'src/browser.dart' show Browser;
 export 'src/common.dart';
 export 'src/query.dart'
     show

objectbox/lib/src/browser.dart

@@ -0,0 +1 @@
+export 'native/browser.dart' if (dart.library.html) 'web/browser.dart';

objectbox/lib/src/native/bindings/bindings.dart

@@ -122,6 +122,8 @@ late final native_query_close =
     _lib!.lookup<NativeFunction<_native_close>>('obx_query_close');
 late final native_query_prop_close =
     _lib!.lookup<NativeFunction<_native_close>>('obx_query_prop_close');
+late final native_browser_close =
+    _lib!.lookup<NativeFunction<_native_close>>('obx_browser_close');
 
 /// Keeps `this` alive until this call, preventing finalizers to run.
 /// Necessary for objects with a finalizer attached because the optimizer may

objectbox/lib/src/native/browser.dart

@@ -0,0 +1,81 @@
+import 'dart:ffi';
+
+import 'bindings/bindings.dart';
+import 'bindings/helpers.dart';
+import 'store.dart';
+
+/// Data browser allows you to explore the DB contents in a regular web browser.
+///
+/// The Browser runs directly on your device or on your development machine.
+/// Behind the scenes this works by bundling a simple HTTP browser into
+/// ObjectBox when building your app. If triggered, it will then provide a basic
+/// web interface to the data and schema.
+class Browser {
+  late Pointer<OBX_browser> _cBrowser;
+  late final Pointer<OBX_dart_finalizer> _cFinalizer;
+
+  @pragma('vm:prefer-inline')
+  Pointer<OBX_browser> get _ptr => (_cBrowser.address != 0)
+      ? _cBrowser
+      : throw StateError('Browser already closed');
+
+  /// Whether the loaded ObjectBox native library supports ObjectBrowser.
+  static bool isAvailable() => C.has_feature(OBXFeature.ObjectBrowser);
+
+  /// Creates a sync client associated with the given store and options.
+  /// This does not initiate any connection attempts yet: call start() to do so.
+  Browser(Store store, {String bindUri = 'http://127.0.0.1:8090'}) {
+    if (!isAvailable()) {
+      throw UnsupportedError(
+          'ObjectBrowser is not available in the loaded ObjectBox runtime library.');
+    }
+    initializeDartAPI();
+
+    final opt = checkObxPtr(C.browser_opt());
+    try {
+      checkObx(
+          C.browser_opt_store(opt, InternalStoreAccess.ptr(store), nullptr));
+      checkObx(C.browser_opt_user_management(opt, false));
+      withNativeString(bindUri,
+          (Pointer<Int8> cStr) => checkObx(C.browser_opt_bind(opt, cStr)));
+    } catch (_) {
+      C.browser_opt_free(opt);
+      rethrow;
+    }
+
+    _cBrowser = C.browser(opt);
+
+    // Keep the finalizer so we can detach it when close() is called manually.
+    _cFinalizer = C.dartc_attach_finalizer(
+        this, native_browser_close, _cBrowser.cast(), 1024 * 1024);
+    if (_cFinalizer == nullptr) {
+      close();
+      throwLatestNativeError();
+    }
+  }
+
+  /// Closes and cleans up all resources used by this ObjectBrowser.
+  void close() {
+    if (_cBrowser.address != 0) {
+      final errors = List.filled(2, 0);
+      if (_cFinalizer != nullptr) {
+        errors[0] = C.dartc_detach_finalizer(_cFinalizer, this);
+      }
+      errors[1] = C.browser_close(_cBrowser);
+      _cBrowser = nullptr;
+      errors.forEach(checkObx);
+    }
+  }
+
+  /// Returns if the browser is already closed and can no longer be used.
+  bool isClosed() => _cBrowser.address == 0;
+
+  /// Port the Browser listens on. This is especially useful if the port was
+  /// assigned automatically (a "0" port was used in the [bindUri]).
+  late final int port = () {
+    final result = C.browser_port(_ptr);
+    reachabilityFence(this);
+    if (result == 0) throwLatestNativeError();
+    return result;
+  }();
+}

objectbox/lib/src/web/browser.dart

@@ -0,0 +1 @@
+

objectbox/test/browser_test.dart

@@ -0,0 +1,40 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:objectbox/objectbox.dart';
+import 'package:test/test.dart';
+
+import 'entity.dart';
+import 'test_env.dart';
+
+void main() {
+  late TestEnv env;
+
+  setUp(() {
+    env = TestEnv('browser');
+  });
+
+  tearDown(() => env.close());
+
+  test('browser', () async {
+    env.box.put(TestEntity.filled());
+
+    final browser = Browser(env.store);
+
+    // Check that it serves requests and has correct permissions configured.
+    final response = await HttpClient()
+        .get('127.0.0.1', browser.port, '/api/v2/auth-info')
+        .then((request) => request.close());
+    expect(response.statusCode, 200);
+    expect(await response.transform(utf8.decoder).join(''),
+        '{"auth":false,"permissions":{"modelRead":true,"modelWrite":true,"objectsRead":true,"objectsWrite":true,"runtimeRead":true,"runtimeWrite":true}}');
+
+    expect(browser.isClosed(), isFalse);
+    browser.close();
+    expect(browser.isClosed(), isTrue);
+    browser.close(); // does nothing
+  },
+      skip: Browser.isAvailable()
+          ? null
+          : 'ObjectBrowser is not available in the loaded library');
+}