@capgo/capacitor-fast-sql 8.2.17 → 8.3.0

package/Package.swift

@@ -25,6 +25,7 @@ let package = Package(
         .testTarget(
             name: "CapgoCapacitorFastSqlPluginTests",
             dependencies: ["CapgoCapacitorFastSqlPlugin"],
-            path: "ios/Tests/CapgoCapacitorFastSqlPluginTests")
+            path: "ios/Tests/CapgoCapacitorFastSqlPluginTests",
+            resources: [.copy("Fixtures")])
     ]
 )

package/README.md

@@ -383,7 +383,7 @@ bypassing Capacitor's standard bridge for better performance with sync operation
 ### connect(...)
 
 ```typescript
-connect(options: SQLConnectionOptions) => Promise<{ port: number; token: string; database: string; }>
+connect(options: SQLConnectionOptions) => Promise<{ port: number; token: string; database: string; persistent?: boolean; binaryProtocolVersion?: number; }>
 ```
 
 Initialize the database connection and start the HTTP server.
@@ -392,7 +392,7 @@ Initialize the database connection and start the HTTP server.
 | ------------- | --------------------------------------------------------------------- | -------------------- |
 | **`options`** | <code><a href="#sqlconnectionoptions">SQLConnectionOptions</a></code> | - Connection options |
 
-**Returns:** <code>Promise&lt;{ port: number; token: string; database: string; }&gt;</code>
+**Returns:** <code>Promise&lt;{ port: number; token: string; database: string; persistent?: boolean; binaryProtocolVersion?: number; }&gt;</code>
 
 **Since:** 0.0.1
 
@@ -419,7 +419,7 @@ Close database connection and stop the HTTP server.
 ### getServerInfo(...)
 
 ```typescript
-getServerInfo(options: { database: string; }) => Promise<{ port: number; token: string; }>
+getServerInfo(options: { database: string; }) => Promise<{ port: number; token: string; persistent?: boolean; binaryProtocolVersion?: number; }>
 ```
 
 Get the HTTP server port and token for direct communication.
@@ -428,7 +428,7 @@ Get the HTTP server port and token for direct communication.
 | ------------- | ---------------------------------- | --------------- |
 | **`options`** | <code>{ database: string; }</code> | - Database name |
 
-**Returns:** <code>Promise&lt;{ port: number; token: string; }&gt;</code>
+**Returns:** <code>Promise&lt;{ port: number; token: string; persistent?: boolean; binaryProtocolVersion?: number; }&gt;</code>
 
 **Since:** 0.0.1
 
@@ -509,12 +509,12 @@ Rollback the current transaction.
 ### getPluginVersion()
 
 ```typescript
-getPluginVersion() => Promise<{ version: string; }>
+getPluginVersion() => Promise<{ version: string; binaryProtocolVersion?: number; }>
 ```
 
 Get the native Capacitor plugin version.
 
-**Returns:** <code>Promise&lt;{ version: string; }&gt;</code>
+**Returns:** <code>Promise&lt;{ version: string; binaryProtocolVersion?: number; }&gt;</code>
 
 **Since:** 0.0.1
 
@@ -548,14 +548,15 @@ or supply a custom Worker. This method is a no-op on iOS and Android.
 
 Database connection options
 
-| Prop                     | Type                 | Description                                                                                                                                                                                                                | Since  |
-| ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
-| **`database`**           | <code>string</code>  | Database name (file will be created in app data directory)                                                                                                                                                                 |        |
-| **`encrypted`**          | <code>boolean</code> | Enable encryption (iOS/Android only)                                                                                                                                                                                       |        |
-| **`encryptionKey`**      | <code>string</code>  | Encryption key (required if encrypted is true)                                                                                                                                                                             |        |
-| **`readOnly`**           | <code>boolean</code> | Open an existing native database read-only. Writes and missing-file opens fail. WAL mode changes are skipped for read-only connections. The web Worker transport rejects this option instead of silently opening writable. |        |
-| **`walMode`**            | <code>boolean</code> | Enable WAL (Write-Ahead Logging) journal mode for better concurrency and performance. Executes `PRAGMA journal_mode = WAL` immediately after opening the database.                                                         | 8.0.49 |
-| **`performancePresets`** | <code>boolean</code> | Apply recommended SQLite performance PRAGMAs after opening the database: `synchronous = NORMAL`, `busy_timeout = 5000`, `cache_size = -2000`, and `foreign_keys = ON`.                                                     | 8.0.49 |
+| Prop                     | Type                                                              | Description                                                                                                                                                                                                                                                                                                                                                  | Default                  | Since  |
+| ------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | ------ |
+| **`transport`**          | <code><a href="#nativesqltransport">NativeSQLTransport</a></code> | Native HTTP data encoding. Binary v1 sends BLOBs as raw bytes without base64. Opt-in on iOS/Android only; requires a native plugin advertising binary v1. JSON remains the default. Binary is experimental; reconsider the default only in a future major after device performance and conformance testing. No failed write is retried on another transport. | <code>'http-json'</code> |        |
+| **`database`**           | <code>string</code>                                               | Database name (file will be created in app data directory)                                                                                                                                                                                                                                                                                                   |                          |        |
+| **`encrypted`**          | <code>boolean</code>                                              | Enable encryption (iOS/Android only)                                                                                                                                                                                                                                                                                                                         |                          |        |
+| **`encryptionKey`**      | <code>string</code>                                               | Encryption key (required if encrypted is true)                                                                                                                                                                                                                                                                                                               |                          |        |
+| **`readOnly`**           | <code>boolean</code>                                              | Open an existing native database read-only. Writes and missing-file opens fail. WAL mode changes are skipped for read-only connections. The web Worker transport rejects this option instead of silently opening writable.                                                                                                                                   |                          |        |
+| **`walMode`**            | <code>boolean</code>                                              | Enable WAL (Write-Ahead Logging) journal mode for better concurrency and performance. Executes `PRAGMA journal_mode = WAL` immediately after opening the database.                                                                                                                                                                                           |                          | 8.0.49 |
+| **`performancePresets`** | <code>boolean</code>                                              | Apply recommended SQLite performance PRAGMAs after opening the database: `synchronous = NORMAL`, `busy_timeout = 5000`, `cache_size = -2000`, and `foreign_keys = ON`.                                                                                                                                                                                       |                          | 8.0.49 |
 
 
 #### SQLResult
@@ -658,15 +659,23 @@ OPFS persistence requires Cross-Origin Isolation headers on your web server:
 `Cross-Origin-Opener-Policy: same-origin` and
 `Cross-Origin-Embedder-Policy: require-corp`.
 
-| Prop          | Type                                                        | Description                                                                                                                                                  | Default           |
-| ------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
-| **`useOpfs`** | <code>boolean</code>                                        | Prefer OPFS persistence via a Web Worker (default: `true`). When OPFS is unavailable, the plugin falls back to a non-persistent database and logs a warning. | <code>true</code> |
-| **`worker`**  | <code><a href="#sqlitewebworker">SqliteWebWorker</a></code> | Custom Worker instance or factory for SQLite Wasm. Advanced: override the default worker from `@sqlite.org/sqlite-wasm`.                                     |                   |
+| Prop                     | Type                                                        | Description                                                                                                                                                                                                                          | Default            |
+| ------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
+| **`useOpfs`**            | <code>boolean</code>                                        | Prefer OPFS persistence via a Web Worker (default: `true`). When OPFS is unavailable, the plugin falls back to a non-persistent database and logs a warning.                                                                         | <code>true</code>  |
+| **`requirePersistence`** | <code>boolean</code>                                        | Reject web connections unless the Worker confirms persistent storage. Defaults to false for compatibility. Consider requiring persistence by default in the next Capacitor major, rather than changing fallback behavior in a minor. | <code>false</code> |
+| **`worker`**             | <code><a href="#sqlitewebworker">SqliteWebWorker</a></code> | Custom Worker instance or factory for SQLite Wasm. Advanced: override the default worker from `@sqlite.org/sqlite-wasm`.                                                                                                             |                    |
 
 
 ### Type Aliases
 
 
+#### NativeSQLTransport
+
+Native HTTP data encoding. JSON remains the compatibility default.
+
+<code>'http-json' | 'http-binary'</code>
+
+
 #### SQLValue
 
 SQL value types supported by the plugin

package/android/build.gradle

@@ -26,6 +26,7 @@ android {
         versionCode 1
         versionName "1.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        consumerProguardFiles 'consumer-rules.pro'
     }
     buildTypes {
         release {
@@ -40,6 +41,9 @@ android {
         sourceCompatibility JavaVersion.VERSION_21
         targetCompatibility JavaVersion.VERSION_21
     }
+    sourceSets {
+        test.resources.srcDir "../ios/Tests/CapgoCapacitorFastSqlPluginTests/Fixtures"
+    }
     testOptions {
         unitTests.includeAndroidResources = true
     }

package/android/consumer-rules.pro

@@ -0,0 +1,14 @@
+# Consumer ProGuard rules for @capgo/capacitor-fast-sql (merged into app R8 when this AAR is a dependency).
+
+# CapgoCapacitorFastSqlPlugin uses Class.forName on this class when encrypted databases are enabled.
+# R8 must keep the type so the optional SQLCipher dependency still resolves at runtime.
+-keep class net.zetetic.database.sqlcipher.SQLiteDatabase { *; }
+
+# SQLCipher is compileOnly and also exposes types such as DatabaseErrorHandler
+# directly under net.zetetic.database. Plain-SQLite apps omit the entire artifact.
+-dontwarn net.zetetic.database.**
+
+# EncryptedSQLDatabase loads the SQLCipher JNI library by name; keep JNI method names linked from Java.
+-keepclasseswithmembernames class * {
+    native <methods>;
+}

package/android/src/main/java/app/capgo/capacitor/fastsql/BinaryFrame.java

@@ -0,0 +1,152 @@
+package app.capgo.capacitor.fastsql;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.nio.charset.CodingErrorAction;
+import java.nio.charset.StandardCharsets;
+import java.util.Iterator;
+import org.json.JSONArray;
+import org.json.JSONObject;
+import org.json.JSONTokener;
+
+/** Shared binary v1 envelope. Byte arrays never pass through base64 or JSON. */
+final class BinaryFrame {
+
+    static final String CONTENT_TYPE = "application/vnd.capgo.fast-sql.v1+binary";
+    static final int MAX_BYTES = 64 * 1024 * 1024;
+    private static final int MAX_METADATA = 1024 * 1024;
+    private static final int HEADER = 12;
+    private static final byte[] MAGIC = { 70, 83, 81, 49 };
+    private int nodes;
+    private int blobs;
+    private long referencedBytes;
+
+    static Object decode(byte[] frame) throws Exception {
+        if (frame.length < HEADER || frame.length > MAX_BYTES) throw new IOException("Invalid binary frame length");
+        for (int i = 0; i < MAGIC.length; i++) if (frame[i] != MAGIC[i]) throw new IOException("Invalid binary frame version");
+        ByteBuffer header = ByteBuffer.wrap(frame).order(ByteOrder.LITTLE_ENDIAN);
+        int metadataLength = header.getInt(4);
+        int payloadLength = header.getInt(8);
+        if (
+            metadataLength <= 0 ||
+            metadataLength > MAX_METADATA ||
+            payloadLength < 0 ||
+            (long) HEADER + metadataLength + payloadLength != frame.length
+        ) throw new IOException("Invalid binary frame lengths");
+        String metadata = StandardCharsets.UTF_8.newDecoder()
+            .onMalformedInput(CodingErrorAction.REPORT)
+            .onUnmappableCharacter(CodingErrorAction.REPORT)
+            .decode(ByteBuffer.wrap(frame, HEADER, metadataLength))
+            .toString();
+        checkNesting(metadata);
+        JSONTokener parser = new JSONTokener(metadata);
+        Object value = parser.nextValue();
+        if (parser.nextClean() != 0) throw new IOException("Trailing binary metadata");
+        return new BinaryFrame().decodeValue(value, frame, HEADER + metadataLength, payloadLength, 0);
+    }
+
+    private static void checkNesting(String json) throws IOException {
+        boolean quoted = false;
+        boolean escaped = false;
+        int depth = 0;
+        for (int i = 0; i < json.length(); i++) {
+            char value = json.charAt(i);
+            if (quoted) {
+                if (escaped) escaped = false;
+                else if (value == 92) escaped = true;
+                else if (value == 34) quoted = false;
+            } else if (value == 34) quoted = true;
+            else if (value == '[' || value == '{') {
+                if (++depth > 33) throw new IOException("Binary metadata nesting exceeds limits");
+            } else if (value == ']' || value == '}') depth--;
+        }
+    }
+
+    private Object decodeValue(Object value, byte[] frame, int payloadStart, int payloadLength, int depth) throws Exception {
+        if (++nodes > 100000 || depth > 32) throw new IOException("Binary metadata exceeds limits");
+        if (value instanceof JSONArray) {
+            JSONArray input = (JSONArray) value;
+            JSONArray result = new JSONArray();
+            for (int i = 0; i < input.length(); i++) result.put(decodeValue(input.get(i), frame, payloadStart, payloadLength, depth + 1));
+            return result;
+        }
+        if (!(value instanceof JSONObject)) return value;
+        JSONObject input = (JSONObject) value;
+        if (input.has("$blob") && input.length() == 1) {
+            JSONArray reference = input.getJSONArray("$blob");
+            if (
+                reference.length() != 2 || !(reference.get(0) instanceof Number) || !(reference.get(1) instanceof Number)
+            ) throw new IOException("Invalid binary attachment reference");
+            double offset = reference.getDouble(0);
+            double length = reference.getDouble(1);
+            if (
+                !Double.isFinite(offset) ||
+                !Double.isFinite(length) ||
+                offset < 0 ||
+                length < 0 ||
+                offset != Math.floor(offset) ||
+                length != Math.floor(length) ||
+                offset + length > payloadLength
+            ) throw new IOException("Binary attachment outside frame");
+            referencedBytes += (long) length;
+            if (++blobs > 4096 || referencedBytes > MAX_BYTES) throw new IOException("Decoded attachments exceed limits");
+            return java.util.Arrays.copyOfRange(frame, payloadStart + (int) offset, payloadStart + (int) offset + (int) length);
+        }
+        JSONObject result = new JSONObject();
+        Iterator<String> keys = input.keys();
+        while (keys.hasNext()) {
+            String key = keys.next();
+            result.put(key, decodeValue(input.get(key), frame, payloadStart, payloadLength, depth + 1));
+        }
+        return result;
+    }
+
+    static byte[] encode(Object value) throws Exception {
+        ByteArrayOutputStream attachments = new ByteArrayOutputStream();
+        BinaryFrame codec = new BinaryFrame();
+        Object metadataValue = codec.encodeValue(value, attachments, 0);
+        String wrapped = new JSONArray().put(metadataValue).toString();
+        byte[] metadata = wrapped.substring(1, wrapped.length() - 1).getBytes(StandardCharsets.UTF_8);
+        long total = (long) HEADER + metadata.length + attachments.size();
+        if (metadata.length > MAX_METADATA || total > MAX_BYTES) throw new IOException("Binary frame exceeds limits");
+        ByteArrayOutputStream output = new ByteArrayOutputStream((int) total);
+        output.write(MAGIC);
+        output.write(ByteBuffer.allocate(8).order(ByteOrder.LITTLE_ENDIAN).putInt(metadata.length).putInt(attachments.size()).array());
+        output.write(metadata);
+        attachments.writeTo(output);
+        return output.toByteArray();
+    }
+
+    private Object encodeValue(Object value, ByteArrayOutputStream attachments, int depth) throws Exception {
+        if (++nodes > 100000 || depth > 32) throw new IOException("Binary metadata exceeds limits");
+        if (value instanceof byte[]) {
+            byte[] bytes = (byte[]) value;
+            if (++blobs > 4096 || (long) attachments.size() + bytes.length > MAX_BYTES - HEADER) throw new IOException(
+                "Binary attachments exceed limits"
+            );
+            JSONObject reference = new JSONObject();
+            reference.put("$blob", new JSONArray().put(attachments.size()).put(bytes.length));
+            attachments.write(bytes);
+            return reference;
+        }
+        if (value instanceof JSONArray) {
+            JSONArray input = (JSONArray) value;
+            JSONArray result = new JSONArray();
+            for (int i = 0; i < input.length(); i++) result.put(encodeValue(input.get(i), attachments, depth + 1));
+            return result;
+        }
+        if (value instanceof JSONObject) {
+            JSONObject input = (JSONObject) value;
+            JSONObject result = new JSONObject();
+            Iterator<String> keys = input.keys();
+            while (keys.hasNext()) {
+                String key = keys.next();
+                result.put(key, encodeValue(input.get(key), attachments, depth + 1));
+            }
+            return result;
+        }
+        return value;
+    }
+}

package/android/src/main/java/app/capgo/capacitor/fastsql/CapgoCapacitorFastSqlPlugin.java

@@ -19,7 +19,7 @@ import java.util.Map;
 @CapacitorPlugin(name = "CapgoCapacitorFastSql")
 public class CapgoCapacitorFastSqlPlugin extends Plugin {
 
-    private final String pluginVersion = "8.2.17";
+    private final String pluginVersion = "8.3.0";
 
     private Map<String, DatabaseConnection> databases = new HashMap<>();
     private SQLHTTPServer server;
@@ -51,6 +51,7 @@ public class CapgoCapacitorFastSqlPlugin extends Plugin {
                 JSObject ret = new JSObject();
                 ret.put("port", server.getPort());
                 ret.put("token", server.getToken());
+                ret.put("binaryProtocolVersion", 1);
                 ret.put("database", database);
                 call.resolve(ret);
                 return;
@@ -89,6 +90,7 @@ public class CapgoCapacitorFastSqlPlugin extends Plugin {
             JSObject ret = new JSObject();
             ret.put("port", server.getPort());
             ret.put("token", server.getToken());
+            ret.put("binaryProtocolVersion", 1);
             ret.put("database", database);
             call.resolve(ret);
         } catch (Exception e) {
@@ -143,6 +145,7 @@ public class CapgoCapacitorFastSqlPlugin extends Plugin {
         JSObject ret = new JSObject();
         ret.put("port", server.getPort());
         ret.put("token", server.getToken());
+        ret.put("binaryProtocolVersion", 1);
         call.resolve(ret);
     }
 
@@ -256,6 +259,7 @@ public class CapgoCapacitorFastSqlPlugin extends Plugin {
     public void getPluginVersion(PluginCall call) {
         JSObject ret = new JSObject();
         ret.put("version", pluginVersion);
+        ret.put("binaryProtocolVersion", 1);
         call.resolve(ret);
     }
 

package/android/src/main/java/app/capgo/capacitor/fastsql/DatabaseConnection.java

@@ -6,6 +6,8 @@ import com.getcapacitor.JSObject;
 public interface DatabaseConnection {
     JSObject execute(String statement, JSArray params) throws Exception;
 
+    JSObject executeBinary(String statement, JSArray params) throws Exception;
+
     void beginTransaction() throws Exception;
 
     void commitTransaction() throws Exception;

package/android/src/main/java/app/capgo/capacitor/fastsql/EncryptedSQLDatabase.java

@@ -56,6 +56,14 @@ public class EncryptedSQLDatabase implements DatabaseConnection {
     }
 
     public JSObject execute(String statement, JSArray params) throws Exception {
+        return execute(statement, params, false);
+    }
+
+    public JSObject executeBinary(String statement, JSArray params) throws Exception {
+        return execute(statement, params, true);
+    }
+
+    private JSObject execute(String statement, JSArray params, boolean binaryResults) throws Exception {
         if (db == null || !db.isOpen()) {
             throw new Exception("Database is not open");
         }
@@ -83,7 +91,7 @@ public class EncryptedSQLDatabase implements DatabaseConnection {
                 JSObject row = new JSObject();
                 for (int i = 0; i < cursor.getColumnCount(); i++) {
                     String columnName = cursor.getColumnName(i);
-                    Object value = getColumnValue(cursor, i);
+                    Object value = getColumnValue(cursor, i, binaryResults);
                     row.put(columnName, value);
                 }
                 rows.put(row);
@@ -165,6 +173,8 @@ public class EncryptedSQLDatabase implements DatabaseConnection {
 
             if (value == null || value == JSONObject.NULL) {
                 stmt.bindNull(index);
+            } else if (value instanceof byte[]) {
+                stmt.bindBlob(index, (byte[]) value);
             } else if (value instanceof String) {
                 stmt.bindString(index, (String) value);
             } else if (value instanceof Integer) {
@@ -192,7 +202,7 @@ public class EncryptedSQLDatabase implements DatabaseConnection {
         }
     }
 
-    private Object getColumnValue(Cursor cursor, int index) {
+    private Object getColumnValue(Cursor cursor, int index, boolean binaryResults) {
         int type = cursor.getType(index);
         switch (type) {
             case Cursor.FIELD_TYPE_NULL:
@@ -205,6 +215,7 @@ public class EncryptedSQLDatabase implements DatabaseConnection {
                 return cursor.getString(index);
             case Cursor.FIELD_TYPE_BLOB:
                 byte[] blob = cursor.getBlob(index);
+                if (binaryResults) return blob;
                 String base64 = Base64.encodeToString(blob, Base64.NO_WRAP);
                 JSObject blobObj = new JSObject();
                 blobObj.put("_type", "binary");

package/android/src/main/java/app/capgo/capacitor/fastsql/SQLDatabase.java

@@ -41,6 +41,14 @@ public class SQLDatabase implements DatabaseConnection {
     }
 
     public JSObject execute(String statement, JSArray params) throws Exception {
+        return execute(statement, params, false);
+    }
+
+    public JSObject executeBinary(String statement, JSArray params) throws Exception {
+        return execute(statement, params, true);
+    }
+
+    private JSObject execute(String statement, JSArray params, boolean binaryResults) throws Exception {
         if (db == null || !db.isOpen()) {
             throw new Exception("Database is not open");
         }
@@ -69,7 +77,7 @@ public class SQLDatabase implements DatabaseConnection {
                 JSObject row = new JSObject();
                 for (int i = 0; i < cursor.getColumnCount(); i++) {
                     String columnName = cursor.getColumnName(i);
-                    Object value = getColumnValue(cursor, i);
+                    Object value = getColumnValue(cursor, i, binaryResults);
                     row.put(columnName, value);
                 }
                 rows.put(row);
@@ -155,6 +163,8 @@ public class SQLDatabase implements DatabaseConnection {
 
             if (value == null || value == JSONObject.NULL) {
                 stmt.bindNull(index);
+            } else if (value instanceof byte[]) {
+                stmt.bindBlob(index, (byte[]) value);
             } else if (value instanceof String) {
                 stmt.bindString(index, (String) value);
             } else if (value instanceof Integer) {
@@ -183,7 +193,7 @@ public class SQLDatabase implements DatabaseConnection {
         }
     }
 
-    private Object getColumnValue(Cursor cursor, int index) {
+    private Object getColumnValue(Cursor cursor, int index, boolean binaryResults) {
         int type = cursor.getType(index);
         switch (type) {
             case Cursor.FIELD_TYPE_NULL:
@@ -196,6 +206,7 @@ public class SQLDatabase implements DatabaseConnection {
                 return cursor.getString(index);
             case Cursor.FIELD_TYPE_BLOB:
                 byte[] blob = cursor.getBlob(index);
+                if (binaryResults) return blob;
                 String base64 = Base64.encodeToString(blob, Base64.NO_WRAP);
                 JSObject blobObj = new JSObject();
                 blobObj.put("_type", "binary");