[Feature] Web Navigator Locks (#54)

Added Navigator locks for web mutexes

Author: stevensJourney

.github/workflows/release.yml

@@ -4,8 +4,8 @@ name: Compile Assets and Create Draft Release
 on:
   push:
     tags:
-      # Trigger on tags beginning with 'v'
-      - 'v*'
+      # Trigger on sqlite_async tags
+      - 'sqlite_async-v*'
 
 jobs:
   release:

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 2024-07-10
+
+### Changes
+
+---
+
+Packages with breaking changes:
+
+ - There are no breaking changes in this release.
+
+Packages with other changes:
+
+ - [`sqlite_async` - `v0.8.1`](#sqlite_async---v081)
+ - [`drift_sqlite_async` - `v0.1.0-alpha.3`](#drift_sqlite_async---v010-alpha3)
+
+Packages with dependency updates only:
+
+> Packages listed below depend on other packages in this workspace that have had changes. Their versions have been incremented to bump the minimum dependency versions of the packages they depend upon in this project.
+
+ - `drift_sqlite_async` - `v0.1.0-alpha.3`
+
+---
+
+#### `sqlite_async` - `v0.8.1`
+
+ - **FEAT**: use navigator locks.
+

README.md

@@ -13,4 +13,4 @@ This monorepo uses [melos](https://melos.invertase.dev/) to handle command and p
 
 To configure the monorepo for development run `melos prepare` after cloning.
 
-For detailed usage, check out the inner [sqlite_async](https://github.com/powersync-ja/sqlite_async.dart/tree/main/packages/sqlite_async) and [drift_sqlite_async](https://github.com/powersync-ja/sqlite_async.dart/tree/main/packages/drift_sqlite_async) packages.
+For detailed usage, check out the inner [sqlite_async](https://github.com/powersync-ja/sqlite_async.dart/tree/main/packages/sqlite_async) and [drift_sqlite_async](https://github.com/powersync-ja/sqlite_async.dart/tree/main/packages/drift_sqlite_async) packages.

packages/drift_sqlite_async/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.1.0-alpha.3
+
+ - Update a dependency to the latest release.
+
 ## 0.1.0-alpha.2
 
 - Update dependency `sqlite_async` to version 0.8.0.

packages/drift_sqlite_async/pubspec.yaml

@@ -1,5 +1,5 @@
 name: drift_sqlite_async
-version: 0.1.0-alpha.2
+version: 0.1.0-alpha.3
 homepage: https://github.com/powersync-ja/sqlite_async.dart
 repository: https://github.com/powersync-ja/sqlite_async.dart
 description: Use Drift with a sqlite_async database, allowing both to be used in the same application.
@@ -15,7 +15,7 @@ environment:
   sdk: ">=3.0.0 <4.0.0"
 dependencies:
   drift: ^2.15.0
-  sqlite_async: ^0.8.0
+  sqlite_async: ^0.8.1
 dev_dependencies:
   build_runner: ^2.4.8
   drift_dev: ^2.15.0

packages/sqlite_async/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.8.1
+
+ - Added Navigator locks for web `Mutex`s.
+
 ## 0.8.0
 
 - Added web support (web functionality is in beta)

packages/sqlite_async/lib/src/common/mutex.dart

@@ -1,8 +1,14 @@
 import 'package:sqlite_async/src/impl/mutex_impl.dart';
 
 abstract class Mutex {
-  factory Mutex() {
-    return MutexImpl();
+  factory Mutex(
+      {
+      /// An optional identifier for this Mutex instance.
+      /// This could be used for platform specific logic or debugging purposes.
+      /// Currently this is not used on native platforms.
+      /// On web this will be used for the lock name if Navigator locks are available.
+      String? identifier}) {
+    return MutexImpl(identifier: identifier);
   }
 
   /// timeout is a timeout for acquiring the lock, not for the callback

packages/sqlite_async/lib/src/impl/stub_mutex.dart

@@ -1,6 +1,10 @@
 import 'package:sqlite_async/src/common/mutex.dart';
 
 class MutexImpl implements Mutex {
+  String? identifier;
+
+  MutexImpl({this.identifier});
+
   @override
   Future<void> close() {
     throw UnimplementedError();

packages/sqlite_async/lib/src/native/native_isolate_mutex.dart

@@ -7,8 +7,8 @@ import 'package:sqlite_async/src/common/mutex.dart';
 import 'package:sqlite_async/src/common/port_channel.dart';
 
 abstract class MutexImpl implements Mutex {
-  factory MutexImpl() {
-    return SimpleMutex();
+  factory MutexImpl({String? identifier}) {
+    return SimpleMutex(identifier: identifier);
   }
 }
 
@@ -19,12 +19,13 @@ class SimpleMutex implements MutexImpl {
   // Adapted from https://github.com/tekartik/synchronized.dart/blob/master/synchronized/lib/src/basic_lock.dart
 
   Future<dynamic>? last;
+  String? identifier;
 
   // Hack to make sure the Mutex is not copied to another isolate.
   // ignore: unused_field
   final Finalizer _f = Finalizer((_) {});
 
-  SimpleMutex();
+  SimpleMutex({this.identifier});
 
   bool get locked => last != null;
 

packages/sqlite_async/lib/src/web/web_mutex.dart

@@ -1,13 +1,37 @@
+import 'dart:async';
+import 'dart:math';
+
+import 'package:meta/meta.dart';
 import 'package:mutex/mutex.dart' as mutex;
+import 'dart:js_interop';
+import 'dart:js_util' as js_util;
+// This allows for checking things like hasProperty without the need for depending on the `js` package
+import 'dart:js_interop_unsafe';
+import 'package:web/web.dart';
+
 import 'package:sqlite_async/src/common/mutex.dart';
 
+@JS('navigator')
+external Navigator get _navigator;
+
 /// Web implementation of [Mutex]
-/// This should use `navigator.locks` in future
 class MutexImpl implements Mutex {
-  late final mutex.Mutex m;
+  late final mutex.Mutex fallback;
+  String? identifier;
+  final String _resolvedIdentifier;
 
-  MutexImpl() {
-    m = mutex.Mutex();
+  MutexImpl({this.identifier})
+
+      /// On web a lock name is required for Navigator locks.
+      /// Having exclusive Mutex instances requires a somewhat unique lock name.
+      /// This provides a best effort unique identifier, if no identifier is provided.
+      /// This should be fine for most use cases:
+      ///    - The uuid package could be added for better uniqueness if required.
+      ///      This would add another package dependency to `sqlite_async` which is potentially unnecessary at this point.
+      /// An identifier should be supplied for better exclusion.
+      : _resolvedIdentifier = identifier ??
+            "${DateTime.now().microsecondsSinceEpoch}-${Random().nextDouble()}" {
+    fallback = mutex.Mutex();
   }
 
   @override
@@ -17,12 +41,111 @@ class MutexImpl implements Mutex {
 
   @override
   Future<T> lock<T>(Future<T> Function() callback, {Duration? timeout}) {
-    // Note this lock is only valid in a single web tab
-    return m.protect(callback);
+    if ((_navigator as JSObject).hasProperty('locks'.toJS).toDart) {
+      return _webLock(callback, timeout: timeout);
+    } else {
+      return _fallbackLock(callback, timeout: timeout);
+    }
+  }
+
+  /// Locks the callback with a standard Mutex from the `mutex` package
+  Future<T> _fallbackLock<T>(Future<T> Function() callback,
+      {Duration? timeout}) {
+    final completer = Completer<T>();
+    // Need to implement timeout manually for this
+    bool isTimedOut = false;
+    Timer? timer;
+    if (timeout != null) {
+      timer = Timer(timeout, () {
+        isTimedOut = true;
+        completer
+            .completeError(TimeoutException('Failed to acquire lock', timeout));
+      });
+    }
+
+    fallback.protect(() async {
+      try {
+        if (isTimedOut) {
+          // Don't actually run logic
+          return;
+        }
+        timer?.cancel();
+        final result = await callback();
+        completer.complete(result);
+      } catch (ex) {
+        completer.completeError(ex);
+      }
+    });
+
+    return completer.future;
+  }
+
+  /// Locks the callback with web Navigator locks
+  Future<T> _webLock<T>(Future<T> Function() callback,
+      {Duration? timeout}) async {
+    final lock = await _getWebLock(timeout);
+    try {
+      final result = await callback();
+      return result;
+    } finally {
+      lock.release();
+    }
+  }
+
+  /// Passing the Dart callback directly to the JS Navigator can cause some weird
+  /// context related bugs. Instead the JS lock callback will return a hold on the lock
+  /// which is represented as a [HeldLock]. This hold can be used when wrapping the Dart
+  /// callback to manage the JS lock.
+  /// This is inspired and adapted from https://github.com/simolus3/sqlite3.dart/blob/7bdca77afd7be7159dbef70fd1ac5aa4996211a9/sqlite3_web/lib/src/locks.dart#L6
+  Future<HeldLock> _getWebLock(Duration? timeout) {
+    final gotLock = Completer<HeldLock>.sync();
+    // Navigator locks can be timed out by using an AbortSignal
+    final controller = AbortController();
+
+    Timer? timer;
+
+    if (timeout != null) {
+      timer = Timer(timeout, () {
+        gotLock
+            .completeError(TimeoutException('Failed to acquire lock', timeout));
+        controller.abort('Timeout'.toJS);
+      });
+    }
+
+    // If timeout occurred before the lock is available, then this callback should not be called.
+    JSPromise jsCallback(JSAny lock) {
+      timer?.cancel();
+
+      // Give the Held lock something to mark this Navigator lock as completed
+      final jsCompleter = Completer.sync();
+      gotLock.complete(HeldLock._(jsCompleter));
+      return jsCompleter.future.toJS;
+    }
+
+    final lockOptions = JSObject();
+    lockOptions['signal'] = controller.signal;
+    final promise = _navigator.locks
+        .request(_resolvedIdentifier, lockOptions, jsCallback.toJS);
+    // A timeout abort will throw an exception which needs to be handled.
+    // There should not be any other unhandled lock errors.
+    js_util.promiseToFuture(promise).catchError((error) {});
+    return gotLock.future;
   }
 
   @override
   Mutex open() {
     return this;
   }
 }
+
+/// This represents a hold on an active Navigator lock.
+/// This is created inside the Navigator lock callback function and is used to release the lock
+/// from an external source.
+@internal
+class HeldLock {
+  final Completer<void> _completer;
+
+  HeldLock._(this._completer);
+
+  void release() => _completer.complete();
+}

packages/sqlite_async/lib/src/web/web_sqlite_open_factory.dart

@@ -55,7 +55,7 @@ class DefaultSqliteOpenFactory
     // cases, we need to implement a mutex locally.
     final mutex = connection.access == AccessMode.throughSharedWorker
         ? null
-        : MutexImpl();
+        : MutexImpl(identifier: path); // Use the DB path as a mutex identifier
 
     return WebDatabase(connection.database, options.mutex ?? mutex);
   }

packages/sqlite_async/pubspec.yaml

@@ -1,6 +1,6 @@
 name: sqlite_async
 description: High-performance asynchronous interface for SQLite on Dart and Flutter.
-version: 0.8.0
+version: 0.8.1
 repository: https://github.com/powersync-ja/sqlite_async.dart
 environment:
   sdk: ">=3.4.0 <4.0.0"
@@ -18,6 +18,7 @@ dependencies:
   collection: ^1.17.0
   mutex: ^3.1.0
   meta: ^1.10.0
+  web: ^0.5.1
 
 dev_dependencies:
   dcli: ^4.0.0