@capgo/capacitor-fast-sql 8.2.17 → 8.3.0

package/dist/plugin.js

@@ -19,6 +19,107 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
         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');
@@ -32,8 +133,20 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
      * 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;
@@ -58,24 +171,7 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
          * @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
@@ -84,26 +180,138 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
          * @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
@@ -230,28 +438,6 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
                 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
          */
@@ -442,20 +628,30 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
             }
         }
         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);
@@ -16936,7 +17132,13 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
          * 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() {
@@ -16953,6 +17155,8 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
             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');
             }
@@ -16962,6 +17166,7 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
                     port: existing.port,
                     token: existing.token,
                     database: options.database,
+                    persistent: existing.persistent,
                 };
             }
             const path = this.dbPath(options.database);
@@ -16975,6 +17180,8 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
                     });
                 }
                 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 });
@@ -16988,7 +17195,16 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
             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 });
@@ -16996,6 +17212,7 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
                 port,
                 token,
                 database: options.database,
+                persistent,
             };
         }
         async disconnect(options) {
@@ -17016,6 +17233,7 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
             return {
                 port: dbInfo.port,
                 token: dbInfo.token,
+                persistent: dbInfo.persistent,
             };
         }
         async execute(options) {