From: stephan Date: Tue, 23 Apr 2024 06:36:28 +0000 (+0000) Subject: Minor touchups in JS docs and exception messages. X-Git-Tag: version-3.46.0~54 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=642e950e637beaa6699db78f3c12f1bceae924b4;p=thirdparty%2Fsqlite.git Minor touchups in JS docs and exception messages. FossilOrigin-Name: 9e7fc9370dfca121244f7a2941e8de629b277f1799f8de08a43ff1d86f94b6f5 --- diff --git a/ext/wasm/api/sqlite3-api-oo1.js b/ext/wasm/api/sqlite3-api-oo1.js index b225d80b96..8cd50a14bb 100644 --- a/ext/wasm/api/sqlite3-api-oo1.js +++ b/ext/wasm/api/sqlite3-api-oo1.js @@ -112,10 +112,11 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){ as a string, an ArrayBuffer, or a Uint8Array. This is a no-op in non-SEE builds. It throws on error and returns - without side effects if its key/textkey options are not of valid - types. + without side effects if none of the key/textkey/hexkey options + are set. It throws if more than one is set or if any are set to + values of an invalid type. - Returns true if it applies the key, else a falsy value. + Returns true if it applies the key, else an unspecified falsy value. */ const dbCtorApplySEEKey = function(db,opt){ if( !capi.sqlite3_key_v2 ) return; @@ -123,7 +124,10 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){ let key; const check = (opt.key ? 1 : 0) + (opt.hexkey ? 1 : 0) + (opt.textkey ? 1 : 0); if( !check ) return; - else if( check>1 ) toss3("Only ONE of (key, hexkey, textkey) may be provided."); + else if( check>1 ){ + toss3(capi.SQLITE_MISUSE, + "Only ONE of (key, hexkey, textkey) may be provided."); + } if( opt.key ){ /* It is not legal to bind an argument to PRAGMA key=?, so we convert it to a hexkey... */ @@ -136,7 +140,9 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){ key = byteArrayToHex(key); keytype = 'hexkey'; }else{ - toss3("Invalid value for the 'key' option. Expecting a string, ArrayBuffer, or Uint8Array."); + toss3(capi.SQLITE_MISUSE, + "Invalid value for the 'key' option. Expecting a string,", + "ArrayBuffer, or Uint8Array."); return; } }else if( opt.textkey ){ @@ -150,7 +156,9 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){ if(key instanceof Uint8Array){ key = new TextDecoder('utf-8').decode(key); }else if('string'!==typeof key){ - toss3("Invalid value for the 'textkey' option. Expecting a string, ArrayBuffer, or Uint8Array."); + toss3(capi.SQLITE_MISUSE, + "Invalid value for the 'textkey' option. Expecting a string,", + "ArrayBuffer, or Uint8Array."); } }else if( opt.hexkey ){ keytype = 'hexkey'; @@ -158,7 +166,9 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){ if((key instanceof ArrayBuffer) || (key instanceof Uint8Array)){ key = byteArrayToHex(key); }else if('string'!==typeof key){ - toss3("Invalid value for the 'hexkey' option. Expecting a string, ArrayBuffer, or Uint8Array."); + toss3(capi.SQLITE_MISUSE, + "Invalid value for the 'hexkey' option. Expecting a string,", + "ArrayBuffer, or Uint8Array."); } /* else assume it's valid hex codes */ }else{ @@ -381,23 +391,33 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){ - `vfs`: the VFS fname //#if enable-see - And, for SEE-capable builds, optionally ONE of the following: + + SEE-capable builds optionally support ONE of the following + additional options: - `key`, `hexkey`, or `textkey`: encryption key as a string, ArrayBuffer, or Uint8Array. These flags function as documented for the SEE pragmas of the same names. Using a byte array for `hexkey` is equivalent to the same series of hex codes in - string form, so '666f6f' is equivalent to - Uint8Array([0x66,0x6f,0x6f]). A `textkey` byte array is assumed - to be UTF-8. A `key` string is transformed into a UTF-8 byte - array, and a `key` byte array is transformed into a `hexkey` - with the same bytes. + string form, so `'666f6f'` is equivalent to + `Uint8Array([0x66,0x6f,0x6f])`. A `textkey` byte array is + assumed to be UTF-8. A `key` string is transformed into a UTF-8 + byte array, and a `key` byte array is transformed into a + `hexkey` with the same bytes. In non-SEE builds, these options are ignored. In SEE builds, `PRAGMA key/textkey/hexkey=X` is executed immediately after opening the db. If more than one of the options is provided, or any option has an invalid argument type, an exception is thrown. + + Note that some DB subclasses may run post-initialization SQL + code, e.g. to set a busy-handler timeout or tweak the page cache + size. Such code is run _after_ the SEE key is applied. If no key + is supplied and the database is encrypted, execution of the + post-initialization SQL will fail, causing the constructor to + throw. + //#endif enable-see The `filename` and `vfs` arguments may be either JS strings or diff --git a/ext/wasm/api/sqlite3-api-prologue.js b/ext/wasm/api/sqlite3-api-prologue.js index c3cc25f43a..849dfe10f2 100644 --- a/ext/wasm/api/sqlite3-api-prologue.js +++ b/ext/wasm/api/sqlite3-api-prologue.js @@ -245,7 +245,7 @@ globalThis.sqlite3ApiBootstrap = function sqlite3ApiBootstrap( The exception's message is created by concatenating its arguments with a space between each, except for the - two-args-with-an-objec form and that the first argument will + two-args-with-an-object form and that the first argument will get coerced to a string, as described above, if it's an integer. diff --git a/manifest b/manifest index 7b3f6096ff..59bddf164c 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C When\srunning\sthe\s'dist'\starget\sin\sext/wasm\sfor\san\sSEE-capable\sbuild,\sensure\sthat\sthe\sresulting\szip\sfile\sand\sdirectory\sname\sinclude\s'-see'. -D 2024-04-23T05:38:49.383 +C Minor\stouchups\sin\sJS\sdocs\sand\sexception\smessages. +D 2024-04-23T06:36:28.862 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724 @@ -607,8 +607,8 @@ F ext/wasm/api/post-js-header.js 04dc12c3edd666b64a1b4ef3b6690c88dcc653f26451fd4 F ext/wasm/api/pre-js.c-pp.js ad906703f7429590f2fbf5e6498513bf727a1a4f0ebfa057afb08161d7511219 F ext/wasm/api/sqlite3-api-cleanup.js d235ad237df6954145404305040991c72ef8b1881715d2a650dda7b3c2576d0e F ext/wasm/api/sqlite3-api-glue.js c744f4b919e1254c898b467573858671a1c8797c2490d0eca2fdbadf2d0ac74b -F ext/wasm/api/sqlite3-api-oo1.js 7a7828c2748d60664f155821fab2d091db23399e64f3470ea14f52080d3573f7 -F ext/wasm/api/sqlite3-api-prologue.js 93a72b07b2a5d964d2edc76a90b439ece49298bd7ba60a1c6ae5d4878213701e +F ext/wasm/api/sqlite3-api-oo1.js 40f6834314b60e636f0046a9c49b8566a992dcf04be9ea593e680c23f6984b2b +F ext/wasm/api/sqlite3-api-prologue.js 34457b25dcf0005c81d76f011f207026ec164f6ff0f69f024b608025ca808ea9 F ext/wasm/api/sqlite3-api-worker1.js 8d9c0562831f62218170a3373468d8a0b7a6503b5985e309b69bf71187b525cf F ext/wasm/api/sqlite3-license-version-header.js 0c807a421f0187e778dc1078f10d2994b915123c1223fe752b60afdcd1263f89 F ext/wasm/api/sqlite3-opfs-async-proxy.js 196ad83d36ca794e564044788c9d21b964679d63cad865f604da37c4afc9a285 @@ -2185,8 +2185,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0 -P b4a6d32662acacb7767cfb9b8e040e6eb1f99322cb7d0cd44e6265e9ac2fb2e8 -R 7804df285b1889ac6d0dbfb4c36fb69b +P 04c552b12e3b77b9dfd83838d35ce19a37ed024a8c18a2000ada10cf3d1eb6ad +R ed22115253110bc0abaf81953307bf22 U stephan -Z 47a1361c4075358585b8d5f5c90006b4 +Z 8b53fb3b4d609195342a0ce669cacf2a # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index a235332cd6..0b66f11a13 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -04c552b12e3b77b9dfd83838d35ce19a37ed024a8c18a2000ada10cf3d1eb6ad \ No newline at end of file +9e7fc9370dfca121244f7a2941e8de629b277f1799f8de08a43ff1d86f94b6f5 \ No newline at end of file