@capgo/capacitor-fast-sql 8.2.17 → 8.3.0

package/dist/plugin.cjs.js

@@ -20,6 +20,107 @@ const CapgoCapacitorFastSql = core.registerPlugin('CapgoCapacitorFastSql', {
     web: () => Promise.resolve().then(function () { return web; }).then((m) => new m.CapgoCapacitorFastSqlWeb()),
 });
 
+/** Version 1 frame: FSQ1, uint32-LE metadata length, uint32-LE attachment length. */
+const BINARY_CONTENT_TYPE = 'application/vnd.capgo.fast-sql.v1+binary';
+const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+const MAX_METADATA_BYTES = 1024 * 1024;
+const MAX_ATTACHMENTS = 4096;
+const HEADER_BYTES = 12;
+const magic = [70, 83, 81, 49];
+function encodeBinaryFrame(value) {
+    const attachments = [];
+    let size = 0;
+    let nodes = 0;
+    const encode = (item, depth) => {
+        if (++nodes > 100000 || depth > 32)
+            throw new Error('Binary metadata exceeds nesting or node limits');
+        if (typeof item === 'number' && !Number.isFinite(item))
+            throw new Error('Non-finite binary protocol number');
+        if (item instanceof Uint8Array) {
+            if (attachments.length >= MAX_ATTACHMENTS || size + item.byteLength > MAX_FRAME_BYTES - HEADER_BYTES)
+                throw new Error('Binary attachments exceed protocol limits');
+            const reference = { $blob: [size, item.byteLength] };
+            attachments.push(item);
+            size += item.byteLength;
+            return reference;
+        }
+        if (Array.isArray(item))
+            return item.map((value) => encode(value, depth + 1));
+        if (item && typeof item === 'object') {
+            if (Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null)
+                throw new Error('Unsupported binary metadata object');
+            return Object.fromEntries(Object.entries(item).map(([key, value]) => [key, encode(value, depth + 1)]));
+        }
+        return item;
+    };
+    const json = JSON.stringify(encode(value, 0));
+    if (json === undefined)
+        throw new Error('Missing binary metadata');
+    const metadata = new TextEncoder().encode(json);
+    const length = HEADER_BYTES + metadata.byteLength + size;
+    if (metadata.byteLength > MAX_METADATA_BYTES || length > MAX_FRAME_BYTES)
+        throw new Error('Binary frame exceeds protocol limits');
+    const frame = new Uint8Array(length);
+    frame.set(magic);
+    const view = new DataView(frame.buffer);
+    view.setUint32(4, metadata.byteLength, true);
+    view.setUint32(8, size, true);
+    frame.set(metadata, HEADER_BYTES);
+    let offset = HEADER_BYTES + metadata.byteLength;
+    for (const attachment of attachments) {
+        frame.set(attachment, offset);
+        offset += attachment.byteLength;
+    }
+    return frame;
+}
+function decodeBinaryFrame(frame) {
+    if (frame.length < HEADER_BYTES ||
+        frame.length > MAX_FRAME_BYTES ||
+        magic.some((byte, index) => frame[index] !== byte)) {
+        throw new Error('Invalid binary frame version or length');
+    }
+    const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+    const metadataLength = view.getUint32(4, true);
+    const payloadLength = view.getUint32(8, true);
+    const payloadOffset = HEADER_BYTES + metadataLength;
+    if (metadataLength === 0 || metadataLength > MAX_METADATA_BYTES || payloadOffset + payloadLength !== frame.length) {
+        throw new Error('Invalid binary frame lengths');
+    }
+    const metadata = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(frame.subarray(HEADER_BYTES, payloadOffset)));
+    let nodes = 0;
+    let blobs = 0;
+    let referencedBytes = 0;
+    const decode = (value, depth) => {
+        if (++nodes > 100000 || depth > 32)
+            throw new Error('Binary metadata exceeds nesting or node limits');
+        if (Array.isArray(value))
+            return value.map((item) => decode(item, depth + 1));
+        if (value === null || typeof value !== 'object')
+            return value;
+        if ('$blob' in value && Object.keys(value).length === 1) {
+            const reference = value.$blob;
+            if (!Array.isArray(reference) || reference.length !== 2)
+                throw new Error('Invalid binary attachment reference');
+            const [offset, length] = reference;
+            if (typeof offset !== 'number' ||
+                typeof length !== 'number' ||
+                !Number.isSafeInteger(offset) ||
+                !Number.isSafeInteger(length) ||
+                offset < 0 ||
+                length < 0 ||
+                offset + length > payloadLength) {
+                throw new Error('Binary attachment is outside its frame');
+            }
+            referencedBytes += length;
+            if (++blobs > MAX_ATTACHMENTS || referencedBytes > MAX_FRAME_BYTES)
+                throw new Error('Decoded attachments exceed protocol limits');
+            return frame.slice(payloadOffset + offset, payloadOffset + offset + length);
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, decode(item, depth + 1)]));
+    };
+    return decode(metadata, 0);
+}
+
 function assertSupportedIsolation(level) {
     if (level !== undefined && level !== exports.IsolationLevel.Serializable) {
         throw new Error('Only SERIALIZABLE transaction isolation is supported');
@@ -33,8 +134,20 @@ function assertSupportedIsolation(level) {
  * Inspired by capacitor-blob-writer's approach to avoid serialization overhead.
  */
 class NativeSQLConnection {
-    constructor(database, port, token) {
+    /** Cumulative data-request payload bytes and JS codec time; excludes HTTP headers/compression. */
+    getTransportMetrics() {
+        return Object.assign({}, this.metrics);
+    }
+    constructor(database, port, token, transport = 'http-json') {
+        this.transport = transport;
         this.inTransaction = false;
+        this.metrics = {
+            dataRequests: 0,
+            requestBytes: 0,
+            responseBytes: 0,
+            encodeMs: 0,
+            decodeMs: 0,
+        };
         this.database = database;
         this.port = port;
         this.token = token;
@@ -59,24 +172,7 @@ class NativeSQLConnection {
      * @returns Query results
      */
     async execute(statement, params) {
-        const response = await this.browserFetch(`${this.baseUrl}/execute`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${this.token}`,
-                'X-Database': this.database,
-            },
-            body: JSON.stringify({
-                statement,
-                params: params ? this.serializeParams(params) : [],
-            }),
-        });
-        if (!response.ok) {
-            const error = await response.text();
-            throw new Error(`SQL execution failed: ${error}`);
-        }
-        const result = await response.json();
-        return this.deserializeResult(result);
+        return this.parseResult(await this.request('/execute', { statement, params: params !== null && params !== void 0 ? params : [] }));
     }
     /**
      * Execute multiple SQL statements in a batch for better performance
@@ -85,26 +181,138 @@ class NativeSQLConnection {
      * @returns Array of results for each operation
      */
     async executeBatch(operations) {
-        const response = await this.browserFetch(`${this.baseUrl}/batch`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${this.token}`,
-                'X-Database': this.database,
-            },
-            body: JSON.stringify({
-                operations: operations.map((op) => ({
-                    statement: op.statement,
-                    params: op.params ? this.serializeParams(op.params) : [],
-                })),
-            }),
+        const result = await this.request('/batch', {
+            operations: operations.map((operation) => { var _a; return ({ statement: operation.statement, params: (_a = operation.params) !== null && _a !== void 0 ? _a : [] }); }),
         });
-        if (!response.ok) {
-            const error = await response.text();
-            throw new Error(`SQL batch execution failed: ${error}`);
+        if (!Array.isArray(result))
+            throw new Error('Invalid batch response');
+        return result.map((item) => this.parseResult(item));
+    }
+    /** Authenticated transport round trip without SQLite, for diagnostic benchmarks. */
+    async echo(value) {
+        const result = this.parseResult(await this.request('/echo', { statement: '', params: [value] }));
+        if (result.rows.length !== 1 || !('value' in result.rows[0]))
+            throw new Error('Invalid echo response');
+        return result.rows[0].value;
+    }
+    async request(path, payload) {
+        var _a;
+        const binary = this.transport === 'http-binary';
+        const start = performance.now();
+        const body = binary
+            ? encodeBinaryFrame(payload)
+            : new TextEncoder().encode(JSON.stringify('params' in payload
+                ? Object.assign(Object.assign({}, payload), { params: this.serializeParams(payload.params) }) : {
+                operations: payload.operations.map((operation) => (Object.assign(Object.assign({}, operation), { params: this.serializeParams(operation.params) }))),
+            }));
+        if (body.byteLength > MAX_FRAME_BYTES)
+            throw new Error('Request exceeds 64 MiB');
+        this.metrics.encodeMs += performance.now() - start;
+        this.metrics.dataRequests++;
+        this.metrics.requestBytes += body.byteLength;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 600000);
+        try {
+            const response = await this.browserFetch(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': binary ? BINARY_CONTENT_TYPE : 'application/json',
+                    Authorization: `Bearer ${this.token}`,
+                    'X-Database': this.database,
+                },
+                body: body.buffer,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorBody = await this.readResponse(response);
+                throw new Error(`SQL request failed (${response.status}): ${new TextDecoder().decode(errorBody).slice(0, 4096)}`);
+            }
+            if (binary && ((_a = response.headers.get('content-type')) === null || _a === void 0 ? void 0 : _a.split(';')[0].trim()) !== BINARY_CONTENT_TYPE)
+                throw new Error('Server did not return binary HTTP v1');
+            const bytes = await this.readResponse(response);
+            this.metrics.responseBytes += bytes.byteLength;
+            const decodeStart = performance.now();
+            const result = binary ? decodeBinaryFrame(bytes) : JSON.parse(new TextDecoder().decode(bytes));
+            this.metrics.decodeMs += performance.now() - decodeStart;
+            return result;
+        }
+        finally {
+            clearTimeout(timeout);
         }
-        const results = await response.json();
-        return results.map((r) => this.deserializeResult(r));
+    }
+    async readResponse(response) {
+        var _a;
+        const declared = response.headers.get('content-length');
+        if (declared !== null && Number(declared) > MAX_FRAME_BYTES) {
+            await ((_a = response.body) === null || _a === void 0 ? void 0 : _a.cancel());
+            throw new Error('Response exceeds 64 MiB');
+        }
+        if (!response.body)
+            return new Uint8Array();
+        const reader = response.body.getReader();
+        const chunks = [];
+        let length = 0;
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                length += chunk.value.byteLength;
+                if (length > MAX_FRAME_BYTES) {
+                    await reader.cancel();
+                    throw new Error('Response exceeds 64 MiB');
+                }
+                chunks.push(chunk.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const result = new Uint8Array(length);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return result;
+    }
+    parseResult(result) {
+        const start = performance.now();
+        if (!result ||
+            typeof result !== 'object' ||
+            !('rows' in result) ||
+            !Array.isArray(result.rows) ||
+            !('rowsAffected' in result) ||
+            typeof result.rowsAffected !== 'number')
+            throw new Error('Invalid SQL response');
+        const rows = result.rows.map((row) => {
+            if (!row || typeof row !== 'object' || Array.isArray(row))
+                throw new Error('Invalid SQL row');
+            const parsed = {};
+            for (const [key, value] of Object.entries(row)) {
+                let scalar;
+                if (value === null ||
+                    typeof value === 'string' ||
+                    typeof value === 'boolean' ||
+                    value instanceof Uint8Array ||
+                    (typeof value === 'number' && Number.isFinite(value)))
+                    scalar = value;
+                else if (value &&
+                    typeof value === 'object' &&
+                    '_type' in value &&
+                    value._type === 'binary' &&
+                    '_data' in value &&
+                    typeof value._data === 'string')
+                    scalar = this.base64ToUint8Array(value._data);
+                else
+                    throw new Error('Invalid SQL value');
+                Object.defineProperty(parsed, key, { value: scalar, enumerable: true, writable: true, configurable: true });
+            }
+            return parsed;
+        });
+        const insertId = 'insertId' in result && typeof result.insertId === 'number' ? result.insertId : undefined;
+        this.metrics.decodeMs += performance.now() - start;
+        return { rows, rowsAffected: result.rowsAffected, insertId };
     }
     /**
      * Begin a transaction
@@ -231,28 +439,6 @@ class NativeSQLConnection {
             return param;
         });
     }
-    /**
-     * Deserialize result from server
-     * Base64-encoded binary data is converted back to Uint8Array
-     */
-    deserializeResult(result) {
-        return {
-            rows: result.rows.map((row) => {
-                const deserializedRow = {};
-                for (const [key, value] of Object.entries(row)) {
-                    if (value && typeof value === 'object' && value._type === 'binary') {
-                        deserializedRow[key] = this.base64ToUint8Array(value._data);
-                    }
-                    else {
-                        deserializedRow[key] = value;
-                    }
-                }
-                return deserializedRow;
-            }),
-            rowsAffected: result.rowsAffected || 0,
-            insertId: result.insertId,
-        };
-    }
     /**
      * Convert Uint8Array to base64 string
      */
@@ -443,20 +629,30 @@ class FastSQL {
         }
     }
     static optionsMatch(left, right) {
-        return (Boolean(left.encrypted) === Boolean(right.encrypted) &&
+        var _a, _b;
+        return (((_a = left.transport) !== null && _a !== void 0 ? _a : 'http-json') === ((_b = right.transport) !== null && _b !== void 0 ? _b : 'http-json') &&
+            Boolean(left.encrypted) === Boolean(right.encrypted) &&
             left.encryptionKey === right.encryptionKey &&
             Boolean(left.readOnly) === Boolean(right.readOnly) &&
             Boolean(left.walMode) === Boolean(right.walMode) &&
             Boolean(left.performancePresets) === Boolean(right.performancePresets));
     }
     static async open(options) {
+        const platform = core.Capacitor.getPlatform();
+        if (options.transport === 'http-binary' && platform !== 'ios' && platform !== 'android') {
+            throw new Error('Binary HTTP transport requires iOS or Android');
+        }
+        if (options.transport === 'http-binary') {
+            const capabilities = await CapgoCapacitorFastSql.getPluginVersion();
+            if (capabilities.binaryProtocolVersion !== 1)
+                throw new Error('Native plugin does not support binary HTTP v1');
+        }
         // Connect via native plugin
         const info = await CapgoCapacitorFastSql.connect(options);
         // Create connection instance appropriate for the current platform
         let connection;
-        const platform = core.Capacitor.getPlatform();
         if (platform === 'android' || platform === 'ios') {
-            connection = new NativeSQLConnection(info.database, info.port, info.token);
+            connection = new NativeSQLConnection(info.database, info.port, info.token, options.transport);
         }
         else {
             connection = new WebSQLConnection(info.database, CapgoCapacitorFastSql);
@@ -1143,7 +1339,13 @@ class CapgoCapacitorFastSqlWeb extends core.WebPlugin {
      * Must be called before connect() when overriding the default worker.
      */
     async configureWeb(config) {
-        this.webConfig = config;
+        if (this.promiserPromise || this.databases.size > 0) {
+            throw new Error('Configure web storage before opening the first database');
+        }
+        if (config.requirePersistence && config.useOpfs === false) {
+            throw new Error('requirePersistence requires OPFS');
+        }
+        this.webConfig = Object.assign({}, config);
         this.promiserPromise = null;
     }
     getPromiser() {
@@ -1160,6 +1362,8 @@ class CapgoCapacitorFastSqlWeb extends core.WebPlugin {
         return `/capgo-fast-sql/${database}.sqlite3`;
     }
     async connect(options) {
+        if (options.transport === 'http-binary')
+            throw new Error('Binary HTTP transport requires iOS or Android');
         if (options.readOnly) {
             throw new Error('Read-only opens are not supported by the SQLite Wasm Worker transport');
         }
@@ -1169,6 +1373,7 @@ class CapgoCapacitorFastSqlWeb extends core.WebPlugin {
                 port: existing.port,
                 token: existing.token,
                 database: options.database,
+                persistent: existing.persistent,
             };
         }
         const path = this.dbPath(options.database);
@@ -1182,6 +1387,8 @@ class CapgoCapacitorFastSqlWeb extends core.WebPlugin {
                 });
             }
             catch (opfsError) {
+                if (this.webConfig.requirePersistence)
+                    throw opfsError;
                 console.warn('[CapgoCapacitorFastSql] OPFS unavailable; web database will not persist across reloads. ' +
                     'Serve with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp.', opfsError);
                 openResult = await promiser('open', { filename: path });
@@ -1195,7 +1402,16 @@ class CapgoCapacitorFastSqlWeb extends core.WebPlugin {
         if (!dbId) {
             throw new Error('Failed to open SQLite Wasm database: missing dbId');
         }
-        await this.applyPerformanceConfig(promiser, dbId, options);
+        try {
+            if (this.webConfig.requirePersistence && !persistent) {
+                throw new Error('SQLite Worker did not confirm persistent storage');
+            }
+            await this.applyPerformanceConfig(promiser, dbId, options);
+        }
+        catch (error) {
+            await promiser({ type: 'close', dbId, args: {} });
+            throw error;
+        }
         const token = this.generateToken();
         const port = this.nextPort++;
         this.databases.set(options.database, { dbId, token, port, persistent });
@@ -1203,6 +1419,7 @@ class CapgoCapacitorFastSqlWeb extends core.WebPlugin {
             port,
             token,
             database: options.database,
+            persistent,
         };
     }
     async disconnect(options) {
@@ -1223,6 +1440,7 @@ class CapgoCapacitorFastSqlWeb extends core.WebPlugin {
         return {
             port: dbInfo.port,
             token: dbInfo.token,
+            persistent: dbInfo.persistent,
         };
     }
     async execute(options) {