Allow passing options to workers when opening databases

Author: simolus3

sqlite3_web/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.0-dev
+
+- Allow passing data to worker when opening databases.
+
 ## 0.2.2
 
 - Recover from worker errors at startup.

sqlite3_web/example/controller.dart

@@ -12,8 +12,8 @@ final class ExampleController extends DatabaseController {
   }
 
   @override
-  Future<WorkerDatabase> openDatabase(
-      WasmSqlite3 sqlite3, String path, String vfs) async {
+  Future<WorkerDatabase> openDatabase(WasmSqlite3 sqlite3, String path,
+      String vfs, JSAny? additionalOptions) async {
     return ExampleDatabase(database: sqlite3.open(path, vfs: vfs));
   }
 }

sqlite3_web/lib/src/client.dart

@@ -403,14 +403,16 @@ final class DatabaseClient implements WebSqlite {
         WorkerConnection connection) async {
       SimpleSuccessResponse response;
       try {
-        response = await connection.sendRequest(
-          CompatibilityCheck(
-            requestId: 0,
-            type: MessageType.dedicatedCompatibilityCheck,
-            databaseName: databaseName,
-          ),
-          MessageType.simpleSuccessResponse,
-        );
+        response = await connection
+            .sendRequest(
+              CompatibilityCheck(
+                requestId: 0,
+                type: MessageType.dedicatedCompatibilityCheck,
+                databaseName: databaseName,
+              ),
+              MessageType.simpleSuccessResponse,
+            )
+            .timeout(_workerInitializationTimeout);
       } on Object {
         return;
       }
@@ -451,14 +453,16 @@ final class DatabaseClient implements WebSqlite {
     Future<void> sharedCompatibilityCheck(WorkerConnection connection) async {
       SimpleSuccessResponse response;
       try {
-        response = await connection.sendRequest(
-          CompatibilityCheck(
-            requestId: 0,
-            type: MessageType.sharedCompatibilityCheck,
-            databaseName: databaseName,
-          ),
-          MessageType.simpleSuccessResponse,
-        );
+        response = await connection
+            .sendRequest(
+              CompatibilityCheck(
+                requestId: 0,
+                type: MessageType.sharedCompatibilityCheck,
+                databaseName: databaseName,
+              ),
+              MessageType.simpleSuccessResponse,
+            )
+            .timeout(_workerInitializationTimeout);
       } on Object {
         return;
       }
@@ -522,7 +526,7 @@ final class DatabaseClient implements WebSqlite {
 
   @override
   Future<Database> connect(String name, StorageMode type, AccessMode access,
-      {bool onlyOpenVfs = false}) async {
+      {bool onlyOpenVfs = false, JSAny? additionalOptions}) async {
     await startWorkers();
 
     WorkerConnection connection;
@@ -553,6 +557,7 @@ final class DatabaseClient implements WebSqlite {
         databaseName: name,
         storageMode: type.resolveToVfs(shared),
         onlyOpenVfs: onlyOpenVfs,
+        additionalData: additionalOptions,
       ),
       MessageType.simpleSuccessResponse,
     );
@@ -564,7 +569,7 @@ final class DatabaseClient implements WebSqlite {
 
   @override
   Future<ConnectToRecommendedResult> connectToRecommended(String name,
-      {bool onlyOpenVfs = false}) async {
+      {bool onlyOpenVfs = false, JSAny? additionalOptions}) async {
     final probed = await runFeatureDetection(databaseName: name);
 
     // If we have an existing database in storage, we want to keep using that
@@ -593,8 +598,8 @@ final class DatabaseClient implements WebSqlite {
 
     final (storage, access) = availableImplementations.firstOrNull ??
         (StorageMode.inMemory, AccessMode.inCurrentContext);
-    final database =
-        await connect(name, storage, access, onlyOpenVfs: onlyOpenVfs);
+    final database = await connect(name, storage, access,
+        onlyOpenVfs: onlyOpenVfs, additionalOptions: additionalOptions);
 
     return ConnectToRecommendedResult(
       database: database,
@@ -621,6 +626,8 @@ final class DatabaseClient implements WebSqlite {
     // because we can actually share database resources between tabs.
     return a.$2.index.compareTo(b.$2.index);
   }
+
+  static const _workerInitializationTimeout = Duration(seconds: 1);
 }
 
 extension on StorageMode {

sqlite3_web/lib/src/database.dart

@@ -23,8 +23,12 @@ abstract base class DatabaseController {
   ///
   /// This should virtually always call `sqlite3.open(path, vfs: vfs)` and wrap
   /// the result in a [WorkerDatabase] subclass.
+  ///
+  /// The [additionalData] can be set by clients when opening the database. It
+  /// might be useful to transport additional options relevant when opening the
+  /// database.
   Future<WorkerDatabase> openDatabase(
-      WasmSqlite3 sqlite3, String path, String vfs);
+      WasmSqlite3 sqlite3, String path, String vfs, JSAny? additionalData);
 
   /// Handles custom requests from clients that are not bound to a database.
   ///
@@ -190,8 +194,12 @@ abstract class WebSqlite {
   /// on the worker when it's first used.
   /// Only opening the VFS can be used to, for instance, check if the database
   /// already exists and to initialize it manually if it doesn't.
+  ///
+  /// The optional [additionalOptions] must be sendable over message ports and
+  /// is passed to [DatabaseController.openDatabase] on the worker opening the
+  /// database.
   Future<Database> connect(String name, StorageMode type, AccessMode access,
-      {bool onlyOpenVfs = false});
+      {bool onlyOpenVfs = false, JSAny? additionalOptions});
 
   /// Starts a feature detection via [runFeatureDetection] and then [connect]s
   /// to the best database available.
@@ -202,8 +210,12 @@ abstract class WebSqlite {
   /// on the worker when it's first used.
   /// Only opening the VFS can be used to, for instance, check if the database
   /// already exists and to initialize it manually if it doesn't.
+  ///
+  /// The optional [additionalOptions] must be sendable over message ports and
+  /// is passed to [DatabaseController.openDatabase] on the worker opening the
+  /// database.
   Future<ConnectToRecommendedResult> connectToRecommended(String name,
-      {bool onlyOpenVfs = false});
+      {bool onlyOpenVfs = false, JSAny? additionalOptions});
 
   /// Entrypoints for workers hosting datbases.
   static void workerEntrypoint({
@@ -224,7 +236,10 @@ abstract class WebSqlite {
     DatabaseController? controller,
   }) {
     return DatabaseClient(
-        worker, wasmModule, controller ?? const _DefaultDatabaseController());
+      worker,
+      wasmModule,
+      controller ?? const _DefaultDatabaseController(),
+    );
   }
 
   /// Connects to an endpoint previously obtained with [Database.additionalConnection].
@@ -255,8 +270,8 @@ final class _DefaultDatabaseController extends DatabaseController {
   }
 
   @override
-  Future<WorkerDatabase> openDatabase(
-      WasmSqlite3 sqlite3, String path, String vfs) async {
+  Future<WorkerDatabase> openDatabase(WasmSqlite3 sqlite3, String path,
+      String vfs, JSAny? additionalOptions) async {
     return _DefaultWorkerDatabase(sqlite3.open(path, vfs: vfs));
   }
 }

sqlite3_web/lib/src/protocol.dart

@@ -47,7 +47,8 @@ enum MessageType<T extends Message> {
 /// Since we're using unsafe JS interop here, these can't be mangled by dart2js.
 /// Thus, we should keep them short.
 class _UniqueFieldNames {
-  static const action = 'a';
+  static const action = 'a'; // Only used in StreamRequest
+  static const additionalData = 'a'; // only used in OpenRequest
   static const buffer = 'b';
   static const columnNames = 'c';
   static const databaseId = 'd';
@@ -214,12 +215,16 @@ final class OpenRequest extends Request {
   final FileSystemImplementation storageMode;
   final bool onlyOpenVfs;
 
+  /// Additional data passsed to `DatabaseController.openDatabase`.
+  final JSAny? additionalData;
+
   OpenRequest({
     required super.requestId,
     required this.wasmUri,
     required this.databaseName,
     required this.storageMode,
     required this.onlyOpenVfs,
+    this.additionalData,
   });
 
   factory OpenRequest.deserialize(JSObject object) {
@@ -230,9 +235,11 @@ final class OpenRequest extends Request {
       wasmUri:
           Uri.parse((object[_UniqueFieldNames.wasmUri] as JSString).toDart),
       requestId: object.requestId,
+      // The onlyOpenVfs and transformedVfsName fields were not set in earlier
+      // clients.
       onlyOpenVfs:
-          // The onlyOpenVfs field was not set in earlier clients.
           (object[_UniqueFieldNames.onlyOpenVfs] as JSBoolean?)?.toDart == true,
+      additionalData: object[_UniqueFieldNames.additionalData],
     );
   }
 
@@ -246,6 +253,7 @@ final class OpenRequest extends Request {
     object[_UniqueFieldNames.storageMode] = storageMode.toJS;
     object[_UniqueFieldNames.wasmUri] = wasmUri.toString().toJS;
     object[_UniqueFieldNames.onlyOpenVfs] = onlyOpenVfs.toJS;
+    object[_UniqueFieldNames.additionalData] = additionalData;
   }
 }
 
@@ -647,6 +655,7 @@ final class StreamRequest extends Request {
   /// updates.
   final bool action;
 
+  @override
   final MessageType<Message> type;
 
   StreamRequest({

sqlite3_web/lib/src/worker.dart

@@ -213,8 +213,8 @@ final class _ClientConnection extends ProtocolChannel
         _ConnectionDatabase? connectionDatabase;
 
         try {
-          database =
-              _runner.findDatabase(request.databaseName, request.storageMode);
+          database = _runner.findDatabase(request.databaseName,
+              request.storageMode, request.additionalData);
 
           await (request.onlyOpenVfs ? database.vfs : database.opened);
 
@@ -392,6 +392,7 @@ final class DatabaseState {
   final int id;
   final String name;
   final FileSystemImplementation mode;
+  final JSAny? additionalOptions;
   int refCount = 1;
 
   Future<WorkerDatabase>? _database;
@@ -402,11 +403,13 @@ final class DatabaseState {
   /// the database is closed.
   FutureOr<void> Function()? closeHandler;
 
-  DatabaseState(
-      {required this.id,
-      required this.runner,
-      required this.name,
-      required this.mode});
+  DatabaseState({
+    required this.id,
+    required this.runner,
+    required this.name,
+    required this.mode,
+    required this.additionalOptions,
+  });
 
   String get vfsName => 'vfs-web-$id';
 
@@ -456,7 +459,7 @@ final class DatabaseState {
         // We still provide support for multiple databases by keeping multiple
         // VFS instances around.
         '/database',
-        vfsName,
+        vfsName, additionalOptions,
       );
     });
 
@@ -599,7 +602,8 @@ final class WorkerRunner {
     }
   }
 
-  DatabaseState findDatabase(String name, FileSystemImplementation mode) {
+  DatabaseState findDatabase(
+      String name, FileSystemImplementation mode, JSAny? additionalOptions) {
     for (final existing in openedDatabases.values) {
       if (existing.refCount != 0 &&
           existing.name == name &&
@@ -615,6 +619,7 @@ final class WorkerRunner {
       runner: this,
       name: name,
       mode: mode,
+      additionalOptions: additionalOptions,
     );
   }
 

sqlite3_web/pubspec.yaml

@@ -1,6 +1,6 @@
 name: sqlite3_web
 description: Utilities to simplify accessing sqlite3 on the web, with automated feature detection.
-version: 0.2.2
+version: 0.3.0-dev
 homepage: https://github.com/simolus3/sqlite3.dart/tree/main/sqlite3_web
 repository: https://github.com/simolus3/sqlite3.dart
 

sqlite3_web/web/controller.dart

@@ -16,14 +16,20 @@ final class ExampleController extends DatabaseController {
   }
 
   @override
-  Future<WorkerDatabase> openDatabase(
-      WasmSqlite3 sqlite3, String path, String vfs) async {
+  Future<WorkerDatabase> openDatabase(WasmSqlite3 sqlite3, String path,
+      String vfs, JSAny? additionalData) async {
     final raw = sqlite3.open(path, vfs: vfs);
     raw.createFunction(
       functionName: 'database_host',
       function: (args) => isInWorker ? 'worker' : 'document',
       argumentCount: const AllowedArgumentCount(0),
     );
+    raw.createFunction(
+      functionName: 'additional_data',
+      function: (args) => (additionalData as JSString).toDart,
+      argumentCount: const AllowedArgumentCount(0),
+    );
+
     return ExampleDatabase(database: raw);
   }
 }

sqlite3_web/web/main.dart

@@ -11,6 +11,7 @@ import 'controller.dart';
 final sqlite3WasmUri = Uri.parse('sqlite3.wasm');
 final workerUri = Uri.parse('worker.dart.js');
 const databaseName = 'database';
+const additionalOptions = 'test-additional-options';
 
 WebSqlite? webSqlite;
 
@@ -160,12 +161,19 @@ Future<JSAny?> _open(String? implementationName, bool onlyOpenVfs) async {
   if (implementationName != null) {
     final split = implementationName.split(':');
 
-    db = await sqlite.connect(databaseName, StorageMode.values.byName(split[0]),
-        AccessMode.values.byName(split[1]),
-        onlyOpenVfs: onlyOpenVfs);
+    db = await sqlite.connect(
+      databaseName,
+      StorageMode.values.byName(split[0]),
+      AccessMode.values.byName(split[1]),
+      onlyOpenVfs: onlyOpenVfs,
+      additionalOptions: additionalOptions.toJS,
+    );
   } else {
-    final result = await sqlite.connectToRecommended(databaseName,
-        onlyOpenVfs: onlyOpenVfs);
+    final result = await sqlite.connectToRecommended(
+      databaseName,
+      onlyOpenVfs: onlyOpenVfs,
+      additionalOptions: additionalOptions.toJS,
+    );
     db = result.database;
     returnValue = '${result.storage.name}:${result.access.name}';
   }
@@ -174,7 +182,16 @@ Future<JSAny?> _open(String? implementationName, bool onlyOpenVfs) async {
 
   // Make sure it works!
   if (!onlyOpenVfs) {
-    await db.select('SELECT database_host()');
+    final rows = await db
+        .select('SELECT database_host() as host, additional_data() as data;');
+    if (rows.length != 1) {
+      throw 'unexpected row count';
+    }
+    final row = rows[0];
+    if (row['data'] != additionalOptions) {
+      throw 'unexpected data: $row';
+    }
+
     listenForUpdates();
   }