@sqlite.org/sqlite-wasm
Version:
SQLite Wasm conveniently wrapped as an ES Module.
877 lines (830 loc) • 32.3 kB
JavaScript
;
(function() {
//#region src/bin/sqlite3-opfs-async-proxy.js
/* @preserve
2022-09-16
The author disclaims copyright to this source code. In place of a
legal notice, here is a blessing:
* May you do good and not evil.
* May you find forgiveness for yourself and forgive others.
* May you share freely, never taking more than you give.
***********************************************************************
A Worker which manages asynchronous OPFS handles on behalf of a
synchronous API which controls it via a combination of Worker
messages, SharedArrayBuffer, and Atomics. It is the asynchronous
counterpart of the API defined in sqlite3-vfs-opfs.js.
Highly indebted to:
https://github.com/rhashimoto/wa-sqlite/blob/master/src/examples/OriginPrivateFileSystemVFS.js
for demonstrating how to use the OPFS APIs.
This file is to be loaded as a Worker. It does not have any direct
access to the sqlite3 JS/WASM bits, so any bits which it needs (most
notably SQLITE_xxx integer codes) have to be imported into it via an
initialization process.
This file represents an implementation detail of a larger piece of
code, and not a public interface. Its details may change at any time
and are not intended to be used by any client-level code.
2022-11-27: Chrome v108 changes some async methods to synchronous, as
documented at:
https://developer.chrome.com/blog/sync-methods-for-accesshandles/
Firefox v111 and Safari 16.4, both released in March 2023, also
include this.
We cannot change to the sync forms at this point without breaking
clients who use Chrome v104-ish or higher. truncate(), getSize(),
flush(), and close() are now (as of v108) synchronous. Calling them
with an "await", as we have to for the async forms, is still legal
with the sync forms but is superfluous. Calling the async forms with
theFunc().then(...) is not compatible with the change to
synchronous, but we do do not use those APIs that way. i.e. we don't
_need_ to change anything for this, but at some point (after Chrome
versions (approximately) 104-107 are extinct) we should change our
usage of those methods to remove the "await".
*/
const urlParams = new URL(globalThis.location.href).searchParams;
const vfsName = urlParams.get("vfs");
if (!vfsName) throw new Error("Expecting vfs=opfs|opfs-wl URL argument for this worker");
/**
We use this to allow us to differentiate debug output from
multiple instances, e.g. multiple Workers to the "opfs"
VFS or both the "opfs" and "opfs-wl" VFSes.
*/
const workerId = Math.random() * 1e7 | 0;
const isWebLocker = "opfs-wl" === urlParams.get("vfs");
const wPost = (type, ...args) => postMessage({
type,
payload: args
});
const installAsyncProxy = function() {
const toss = function(...args) {
throw new Error(args.join(" "));
};
if (globalThis.window === globalThis) toss("This code cannot run from the main thread.", "Load it as a Worker from a separate Worker.");
else if (!navigator?.storage?.getDirectory) toss("This API requires navigator.storage.getDirectory.");
/**
Will hold state copied to this object from the synchronous side of
this API.
*/
const state = Object.create(null);
const initS11n = function() {
/**
This proxy de/serializes cross-thread function arguments and
output-pointer values via the state.sabIO SharedArrayBuffer,
using the region defined by (state.sabS11nOffset,
state.sabS11nOffset + state.sabS11nSize]. Only one dataset is
recorded at a time.
This is not a general-purpose format. It only supports the
range of operations, and data sizes, needed by the
sqlite3_vfs and sqlite3_io_methods operations. Serialized
data are transient and this serialization algorithm may
change at any time.
The data format can be succinctly summarized as:
Nt...Td...D
Where:
- N = number of entries (1 byte)
- t = type ID of first argument (1 byte)
- ...T = type IDs of the 2nd and subsequent arguments (1 byte
each).
- d = raw bytes of first argument (per-type size).
- ...D = raw bytes of the 2nd and subsequent arguments (per-type
size).
All types except strings have fixed sizes. Strings are stored
using their TextEncoder/TextDecoder representations. It would
arguably make more sense to store them as Int16Arrays of
their JS character values, but how best/fastest to get that
in and out of string form is an open point. Initial
experimentation with that approach did not gain us any speed.
Historical note: this impl was initially about 1% this size by
using using JSON.stringify/parse(), but using fit-to-purpose
serialization saves considerable runtime.
*/
if (state.s11n) return state.s11n;
const textDecoder = new TextDecoder(), textEncoder = new TextEncoder("utf-8"), viewU8 = new Uint8Array(state.sabIO, state.sabS11nOffset, state.sabS11nSize), viewDV = new DataView(state.sabIO, state.sabS11nOffset, state.sabS11nSize);
state.s11n = Object.create(null);
const TypeIds = Object.create(null);
TypeIds.number = {
id: 1,
size: 8,
getter: "getFloat64",
setter: "setFloat64"
};
TypeIds.bigint = {
id: 2,
size: 8,
getter: "getBigInt64",
setter: "setBigInt64"
};
TypeIds.boolean = {
id: 3,
size: 4,
getter: "getInt32",
setter: "setInt32"
};
TypeIds.string = { id: 4 };
const getTypeId = (v) => TypeIds[typeof v] || toss("Maintenance required: this value type cannot be serialized.", v);
const getTypeIdById = (tid) => {
switch (tid) {
case TypeIds.number.id: return TypeIds.number;
case TypeIds.bigint.id: return TypeIds.bigint;
case TypeIds.boolean.id: return TypeIds.boolean;
case TypeIds.string.id: return TypeIds.string;
default: toss("Invalid type ID:", tid);
}
};
/**
Returns an array of the deserialized state stored by the most
recent serialize() operation (from this thread or the
counterpart thread), or null if the serialization buffer is
empty. If passed a truthy argument, the serialization buffer
is cleared after deserialization.
*/
state.s11n.deserialize = function(clear = false) {
performance.now();
const argc = viewU8[0];
const rc = argc ? [] : null;
if (argc) {
const typeIds = [];
let offset = 1, i, n, v;
for (i = 0; i < argc; ++i, ++offset) typeIds.push(getTypeIdById(viewU8[offset]));
for (i = 0; i < argc; ++i) {
const t = typeIds[i];
if (t.getter) {
v = viewDV[t.getter](offset, state.littleEndian);
offset += t.size;
} else {
n = viewDV.getInt32(offset, state.littleEndian);
offset += 4;
v = textDecoder.decode(viewU8.slice(offset, offset + n));
offset += n;
}
rc.push(v);
}
}
if (clear) viewU8[0] = 0;
return rc;
};
/**
Serializes all arguments to the shared buffer for consumption
by the counterpart thread.
This routine is only intended for serializing OPFS VFS
arguments and (in at least one special case) result values,
and the buffer is sized to be able to comfortably handle
those.
If passed no arguments then it zeroes out the serialization
state.
*/
state.s11n.serialize = function(...args) {
performance.now();
if (args.length) {
const typeIds = [];
let i = 0, offset = 1;
viewU8[0] = args.length & 255;
for (; i < args.length; ++i, ++offset) {
typeIds.push(getTypeId(args[i]));
viewU8[offset] = typeIds[i].id;
}
for (i = 0; i < args.length; ++i) {
const t = typeIds[i];
if (t.setter) {
viewDV[t.setter](offset, args[i], state.littleEndian);
offset += t.size;
} else {
const s = textEncoder.encode(args[i]);
viewDV.setInt32(offset, s.byteLength, state.littleEndian);
offset += 4;
viewU8.set(s, offset);
offset += s.byteLength;
}
}
} else viewU8[0] = 0;
};
state.s11n.storeException = state.asyncS11nExceptions ? ((priority, e) => {
if (priority <= state.asyncS11nExceptions) state.s11n.serialize([
e.name,
": ",
e.message
].join(""));
}) : () => {};
return state.s11n;
};
/**
verbose:
0 = no logging output
1 = only errors
2 = warnings and errors
3 = debug, warnings, and errors
*/
state.verbose = 1;
const loggers = {
0: console.error.bind(console),
1: console.warn.bind(console),
2: console.log.bind(console)
};
const logImpl = (level, ...args) => {
if (state.verbose > level) loggers[level](vfsName + " async-proxy", workerId + ":", ...args);
};
const log = (...args) => logImpl(2, ...args);
const warn = (...args) => logImpl(1, ...args);
const error = (...args) => logImpl(0, ...args);
/**
__openFiles is a map of sqlite3_file pointers (integers) to
metadata related to a given OPFS file handles. The pointers are, in
this side of the interface, opaque file handle IDs provided by the
synchronous part of this constellation. Each value is an object
with a structure demonstrated in the xOpen() impl.
*/
const __openFiles = Object.create(null);
/**
__implicitLocks is a Set of sqlite3_file pointers (integers)
which were "auto-locked". i.e. those for which we necessarily
obtain a sync access handle without an explicit xLock() call
guarding access. Such locks will be released during
`waitLoop()`'s idle time, whereas a sync access handle obtained
via xLock(), or subsequently xLock()'d after auto-acquisition,
will not be released until xUnlock() is called.
Maintenance reminder: if we relinquish auto-locks at the end of the
operation which acquires them, we pay a massive performance
penalty: speedtest1 benchmarks take up to 4x as long. By delaying
the lock release until idle time, the hit is negligible.
*/
const __implicitLocks = /* @__PURE__ */ new Set();
/**
Expects an OPFS file path. It gets resolved, such that ".."
components are properly expanded, and returned. If the 2nd arg is
true, the result is returned as an array of path elements, else an
absolute path string is returned.
*/
const getResolvedPath = function(filename, splitIt) {
const p = new URL(filename, "file://irrelevant").pathname;
return splitIt ? p.split("/").filter((v) => !!v) : p;
};
/**
Takes the absolute path to a filesystem element. Returns an array
of [handleOfContainingDir, filename]. If the 2nd argument is truthy
then each directory element leading to the file is created along
the way. Throws if any creation or resolution fails.
*/
const getDirForFilename = async function f(absFilename, createDirs = false) {
const path = getResolvedPath(absFilename, true);
const filename = path.pop();
let dh = state.rootDir;
for (const dirName of path) if (dirName) dh = await dh.getDirectoryHandle(dirName, { create: !!createDirs });
return [dh, filename];
};
/**
If the given file-holding object has a sync handle attached to it,
that handle is removed and asynchronously closed. Though it may
sound sensible to continue work as soon as the close() returns
(noting that it's asynchronous), doing so can cause operations
performed soon afterwards, e.g. a call to getSyncHandle(), to fail
because they may happen out of order from the close(). OPFS does
not guaranty that the actual order of operations is retained in
such cases. i.e. always "await" on the result of this function.
*/
const closeSyncHandle = async (fh) => {
if (fh.syncHandle) {
log("Closing sync handle for", fh.filenameAbs);
const h = fh.syncHandle;
delete fh.syncHandle;
delete fh.xLock;
__implicitLocks.delete(fh.fid);
return h.close();
}
};
/**
A proxy for closeSyncHandle() which is guaranteed to not throw.
This function is part of a lock/unlock step in functions which
require a sync access handle but may be called without xLock()
having been called first. Such calls need to release that
handle to avoid locking the file for all of time. This is an
_attempt_ at reducing cross-tab contention but it may prove
to be more of a problem than a solution and may need to be
removed.
*/
const closeSyncHandleNoThrow = async (fh) => {
try {
await closeSyncHandle(fh);
} catch (e) {
warn("closeSyncHandleNoThrow() ignoring:", e, fh);
}
};
const releaseImplicitLocks = async () => {
if (__implicitLocks.size) for (const fid of __implicitLocks) {
const fh = __openFiles[fid];
await closeSyncHandleNoThrow(fh);
log("Auto-unlocked", fid, fh.filenameAbs);
}
};
/**
An experiment in improving concurrency by freeing up implicit locks
sooner. This is known to impact performance dramatically but it has
also shown to improve concurrency considerably.
If fh.releaseImplicitLocks is truthy and fh is in __implicitLocks,
this routine returns closeSyncHandleNoThrow(), else it is a no-op.
*/
const releaseImplicitLock = async (fh) => {
if (fh.releaseImplicitLocks && __implicitLocks.has(fh.fid)) return closeSyncHandleNoThrow(fh);
};
/**
An error class specifically for use with getSyncHandle(), the goal
of which is to eventually be able to distinguish unambiguously
between locking-related failures and other types, noting that we
cannot currently do so because createSyncAccessHandle() does not
define its exceptions in the required level of detail.
2022-11-29: according to:
https://github.com/whatwg/fs/pull/21
NoModificationAllowedError will be the standard exception thrown
when acquisition of a sync access handle fails due to a locking
error. As of this writing, that error type is not visible in the
dev console in Chrome v109, nor is it documented in MDN, but an
error with that "name" property is being thrown from the OPFS
layer.
*/
class GetSyncHandleError extends Error {
constructor(errorObject, ...msg) {
super([
...msg,
": " + errorObject.name + ":",
errorObject.message
].join(" "), { cause: errorObject });
this.name = "GetSyncHandleError";
}
}
/**
Attempts to find a suitable SQLITE_xyz result code for Error
object e. Returns either such a translation or rc if if it does
not know how to translate the exception.
*/
GetSyncHandleError.convertRc = (e, rc) => {
if (e instanceof GetSyncHandleError) {
if (e.cause.name === "NoModificationAllowedError" || e.cause.name === "DOMException" && 0 === e.cause.message.indexOf("Access Handles cannot")) return state.sq3Codes.SQLITE_BUSY;
else if ("NotFoundError" === e.cause.name)
/**
Maintenance reminder: SQLITE_NOTFOUND, though it looks like
a good match, has different semantics than NotFoundError
and is not suitable here.
*/
return state.sq3Codes.SQLITE_CANTOPEN;
} else if ("NotFoundError" === e?.name) return state.sq3Codes.SQLITE_CANTOPEN;
return rc;
};
/**
Returns the sync access handle associated with the given file
handle object (which must be a valid handle object, as created by
xOpen()), lazily opening it if needed.
In order to help alleviate cross-tab contention for a dabase, if
an exception is thrown while acquiring the handle, this routine
will wait briefly and try again, up to `maxTries` of times. If
acquisition still fails at that point it will give up and
propagate the exception. Client-level code will see that either
as an I/O error or SQLITE_BUSY, depending on the exception and
the context.
2024-06-12: there is a rare race condition here which has been
reported a single time:
https://sqlite.org/forum/forumpost/9ee7f5340802d600
What appears to be happening is that file we're waiting for a
lock on is deleted while we wait. What currently happens here is
that a locking exception is thrown but the exception type is
NotFoundError. In such cases, we very probably should attempt to
re-open/re-create the file an obtain the lock on it (noting that
there's another race condition there). That's easy to say but
creating a viable test for that condition has proven challenging
so far.
Interface quirk: if fh.xLock is falsy and the handle is acquired
then fh.fid is added to __implicitLocks(). If fh.xLock is truthy,
it is not added as an implicit lock. i.e. xLock() impls must set
fh.xLock immediately _before_ calling this and must arrange to
restore it to its previous value if this function throws.
2026-03-06:
- baseWaitTime is the number of milliseconds to wait for the
first retry, increasing by one factor for each retry. It defaults
to (state.asyncIdleWaitTime*2).
- maxTries is the number of attempt to make, each one spaced out
by one additional factor of the baseWaitTime (e.g. 300, then 600,
then 900, the 1200...). This MUST be an integer >0.
Only the Web Locks impl should use the 3rd and 4th parameters.
*/
const getSyncHandle = async (fh, opName, baseWaitTime, maxTries = 6) => {
if (!fh.syncHandle) {
const t = performance.now();
log("Acquiring sync handle for", fh.filenameAbs);
const msBase = baseWaitTime ?? state.asyncIdleWaitTime * 2;
maxTries ??= 6;
let i = 1, ms = msBase;
for (;; ms = msBase * ++i) try {
fh.syncHandle = await fh.fileHandle.createSyncAccessHandle();
break;
} catch (e) {
if (i === maxTries) throw new GetSyncHandleError(e, "Error getting sync handle for", opName + "().", maxTries, "attempts failed.", fh.filenameAbs);
warn("Error getting sync handle for", opName + "(). Waiting", ms, "ms and trying again.", fh.filenameAbs, e);
Atomics.wait(state.sabOPView, state.opIds.retry, 0, ms);
}
log("Got", opName + "() sync handle for", fh.filenameAbs, "in", performance.now() - t, "ms");
if (!fh.xLock) {
__implicitLocks.add(fh.fid);
log("Acquired implicit lock for", opName + "()", fh.fid, fh.filenameAbs);
}
}
return fh.syncHandle;
};
/**
Stores the given value at state.sabOPView[state.opIds.rc] and then
Atomics.notify()'s it.
The opName is only used for logging and debugging - all result
codes are expected on the same state.sabOPView slot.
*/
const storeAndNotify = (opName, value) => {
log(opName + "() => notify(", value, ")");
Atomics.store(state.sabOPView, state.opIds.rc, value);
Atomics.notify(state.sabOPView, state.opIds.rc);
};
/**
Throws if fh is a file-holding object which is flagged as read-only.
*/
const affirmNotRO = function(opName, fh) {
if (fh.readOnly) toss(opName + "(): File is read-only: " + fh.filenameAbs);
};
/**
Gets set to true by the 'opfs-async-shutdown' command to quit the
wait loop. This is only intended for debugging purposes: we cannot
inspect this file's state while the tight waitLoop() is running and
need a way to stop that loop for introspection purposes.
*/
let flagAsyncShutdown = false;
/**
Asynchronous wrappers for sqlite3_vfs and sqlite3_io_methods
methods, as well as helpers like mkdir().
*/
const vfsAsyncImpls = {
"opfs-async-shutdown": async () => {
flagAsyncShutdown = true;
storeAndNotify("opfs-async-shutdown", 0);
},
mkdir: async (dirname) => {
let rc = 0;
try {
await getDirForFilename(dirname + "/filepart", true);
} catch (e) {
state.s11n.storeException(2, e);
rc = state.sq3Codes.SQLITE_IOERR;
}
storeAndNotify("mkdir", rc);
},
xAccess: async (filename) => {
let rc = 0;
try {
const [dh, fn] = await getDirForFilename(filename);
await dh.getFileHandle(fn);
} catch (e) {
state.s11n.storeException(2, e);
rc = state.sq3Codes.SQLITE_IOERR;
}
storeAndNotify("xAccess", rc);
},
xClose: async function(fid) {
const opName = "xClose";
__implicitLocks.delete(fid);
const fh = __openFiles[fid];
let rc = 0;
if (fh) {
delete __openFiles[fid];
await closeSyncHandle(fh);
if (fh.deleteOnClose) try {
await fh.dirHandle.removeEntry(fh.filenamePart);
} catch (e) {
warn("Ignoring dirHandle.removeEntry() failure of", fh, e);
}
} else {
state.s11n.serialize();
rc = state.sq3Codes.SQLITE_NOTFOUND;
}
storeAndNotify(opName, rc);
},
xDelete: async function(...args) {
storeAndNotify("xDelete", await vfsAsyncImpls.xDeleteNoWait(...args));
},
xDeleteNoWait: async function(filename, syncDir = 0, recursive = false) {
let rc = 0;
try {
while (filename) {
const [hDir, filenamePart] = await getDirForFilename(filename, false);
if (!filenamePart) break;
await hDir.removeEntry(filenamePart, { recursive });
if (4660 !== syncDir) break;
recursive = false;
filename = getResolvedPath(filename, true);
filename.pop();
filename = filename.join("/");
}
} catch (e) {
state.s11n.storeException(2, e);
rc = state.sq3Codes.SQLITE_IOERR_DELETE;
}
return rc;
},
xFileSize: async function(fid) {
const fh = __openFiles[fid];
let rc = 0;
try {
const sz = await (await getSyncHandle(fh, "xFileSize")).getSize();
state.s11n.serialize(Number(sz));
} catch (e) {
state.s11n.storeException(1, e);
rc = GetSyncHandleError.convertRc(e, state.sq3Codes.SQLITE_IOERR);
}
await releaseImplicitLock(fh);
storeAndNotify("xFileSize", rc);
},
xOpen: async function(fid, filename, flags, opfsFlags) {
const opName = "xOpen";
const create = state.sq3Codes.SQLITE_OPEN_CREATE & flags;
try {
let hDir, filenamePart;
try {
[hDir, filenamePart] = await getDirForFilename(filename, !!create);
} catch (e) {
state.s11n.storeException(1, e);
storeAndNotify(opName, state.sq3Codes.SQLITE_NOTFOUND);
return;
}
if (state.opfsFlags.OPFS_UNLINK_BEFORE_OPEN & opfsFlags) try {
await hDir.removeEntry(filenamePart);
} catch (e) {}
const hFile = await hDir.getFileHandle(filenamePart, { create });
const fh = Object.assign(Object.create(null), {
fid,
filenameAbs: filename,
filenamePart,
dirHandle: hDir,
fileHandle: hFile,
sabView: state.sabFileBufView,
readOnly: !create && !!(state.sq3Codes.SQLITE_OPEN_READONLY & flags),
deleteOnClose: !!(state.sq3Codes.SQLITE_OPEN_DELETEONCLOSE & flags)
});
fh.releaseImplicitLocks = opfsFlags & state.opfsFlags.OPFS_UNLOCK_ASAP || state.opfsFlags.defaultUnlockAsap;
__openFiles[fid] = fh;
storeAndNotify(opName, 0);
} catch (e) {
error(opName, e);
state.s11n.storeException(1, e);
storeAndNotify(opName, state.sq3Codes.SQLITE_IOERR);
}
},
xRead: async function(fid, n, offset64) {
let rc = 0, nRead;
const fh = __openFiles[fid];
try {
nRead = (await getSyncHandle(fh, "xRead")).read(fh.sabView.subarray(0, n), { at: Number(offset64) });
if (nRead < n) {
fh.sabView.fill(0, nRead, n);
rc = state.sq3Codes.SQLITE_IOERR_SHORT_READ;
}
} catch (e) {
state.s11n.storeException(1, e);
rc = GetSyncHandleError.convertRc(e, state.sq3Codes.SQLITE_IOERR_READ);
}
await releaseImplicitLock(fh);
storeAndNotify("xRead", rc);
},
xSync: async function(fid, flags) {
const fh = __openFiles[fid];
let rc = 0;
if (!fh.readOnly && fh.syncHandle) try {
await fh.syncHandle.flush();
} catch (e) {
state.s11n.storeException(2, e);
rc = state.sq3Codes.SQLITE_IOERR_FSYNC;
}
storeAndNotify("xSync", rc);
},
xTruncate: async function(fid, size) {
let rc = 0;
const fh = __openFiles[fid];
try {
affirmNotRO("xTruncate", fh);
await (await getSyncHandle(fh, "xTruncate")).truncate(size);
} catch (e) {
state.s11n.storeException(2, e);
rc = GetSyncHandleError.convertRc(e, state.sq3Codes.SQLITE_IOERR_TRUNCATE);
}
await releaseImplicitLock(fh);
storeAndNotify("xTruncate", rc);
},
xWrite: async function(fid, n, offset64) {
let rc;
const fh = __openFiles[fid];
try {
affirmNotRO("xWrite", fh);
rc = n === (await getSyncHandle(fh, "xWrite")).write(fh.sabView.subarray(0, n), { at: Number(offset64) }) ? 0 : state.sq3Codes.SQLITE_IOERR_WRITE;
} catch (e) {
state.s11n.storeException(1, e);
rc = GetSyncHandleError.convertRc(e, state.sq3Codes.SQLITE_IOERR_WRITE);
}
await releaseImplicitLock(fh);
storeAndNotify("xWrite", rc);
}
};
if (isWebLocker) {
/** Registry of active Web Locks: fid -> { mode, resolveRelease } */
const __activeWebLocks = Object.create(null);
vfsAsyncImpls.xLock = async function(fid, lockType, isFromUnlock) {
const whichOp = isFromUnlock ? "xUnlock" : "xLock";
const fh = __openFiles[fid];
const requestedMode = lockType >= state.sq3Codes.SQLITE_LOCK_RESERVED ? "exclusive" : "shared";
const existing = __activeWebLocks[fid];
if (existing) {
if (existing.mode === requestedMode || existing.mode === "exclusive" && requestedMode === "shared") {
fh.xLock = lockType;
storeAndNotify(whichOp, 0);
return 0;
}
await closeSyncHandle(fh);
existing.resolveRelease();
delete __activeWebLocks[fid];
}
const lockName = "sqlite3-vfs-opfs:" + fh.filenameAbs;
const oldLockType = fh.xLock;
return new Promise((resolveWaitLoop) => {
navigator.locks.request(lockName, { mode: requestedMode }, async (lock) => {
__implicitLocks.delete(fid);
let rc = 0;
try {
fh.xLock = lockType;
await getSyncHandle(fh, "xLock", state.asyncIdleWaitTime, 5);
} catch (e) {
fh.xLock = oldLockType;
state.s11n.storeException(1, e);
rc = GetSyncHandleError.convertRc(e, state.sq3Codes.SQLITE_BUSY);
}
const releasePromise = rc ? void 0 : new Promise((resolveRelease) => {
__activeWebLocks[fid] = {
mode: requestedMode,
resolveRelease
};
});
storeAndNotify(whichOp, rc);
resolveWaitLoop(0);
await releasePromise;
});
});
};
/** Internal helper for the opfs-wl xUnlock() */
const wlCloseHandle = async (fh) => {
let rc = 0;
try {
await closeSyncHandle(fh);
} catch (e) {
state.s11n.storeException(1, e);
rc = state.sq3Codes.SQLITE_IOERR_UNLOCK;
}
return rc;
};
vfsAsyncImpls.xUnlock = async function(fid, lockType) {
const fh = __openFiles[fid];
const existing = __activeWebLocks[fid];
if (!existing) {
const rc = await wlCloseHandle(fh);
storeAndNotify("xUnlock", rc);
return rc;
}
let rc = 0;
if (lockType === state.sq3Codes.SQLITE_LOCK_NONE) {
rc = await wlCloseHandle(fh);
existing.resolveRelease();
delete __activeWebLocks[fid];
fh.xLock = lockType;
} else if (lockType === state.sq3Codes.SQLITE_LOCK_SHARED && existing.mode === "exclusive") {
rc = await wlCloseHandle(fh);
if (0 === rc) {
fh.xLock = lockType;
existing.resolveRelease();
delete __activeWebLocks[fid];
return vfsAsyncImpls.xLock(fid, lockType, true);
}
} else error("xUnlock() unhandled condition", fh);
storeAndNotify("xUnlock", rc);
return 0;
};
} else {
vfsAsyncImpls.xLock = async function(fid, lockType) {
const fh = __openFiles[fid];
let rc = 0;
const oldLockType = fh.xLock;
fh.xLock = lockType;
if (!fh.syncHandle) try {
await getSyncHandle(fh, "xLock");
__implicitLocks.delete(fid);
} catch (e) {
state.s11n.storeException(1, e);
rc = GetSyncHandleError.convertRc(e, state.sq3Codes.SQLITE_IOERR_LOCK);
fh.xLock = oldLockType;
}
storeAndNotify("xLock", rc);
};
vfsAsyncImpls.xUnlock = async function(fid, lockType) {
let rc = 0;
const fh = __openFiles[fid];
if (fh.syncHandle && state.sq3Codes.SQLITE_LOCK_NONE === lockType) try {
await closeSyncHandle(fh);
} catch (e) {
state.s11n.storeException(1, e);
rc = state.sq3Codes.SQLITE_IOERR_UNLOCK;
}
storeAndNotify("xUnlock", rc);
};
}
const waitLoop = async function f() {
if (!f.inited) {
f.inited = true;
f.opHandlers = Object.create(null);
for (let k of Object.keys(state.opIds)) {
const vi = vfsAsyncImpls[k];
if (!vi) continue;
const o = Object.create(null);
f.opHandlers[state.opIds[k]] = o;
o.key = k;
o.f = vi;
}
}
const opIds = state.opIds;
const opView = state.sabOPView;
const slotWhichOp = opIds.whichOp;
const idleWaitTime = state.asyncIdleWaitTime;
const hasWaitAsync = !!Atomics.waitAsync;
while (!flagAsyncShutdown) try {
let opId;
if (hasWaitAsync) {
opId = Atomics.load(opView, slotWhichOp);
if (0 === opId) {
const rv = Atomics.waitAsync(opView, slotWhichOp, 0, idleWaitTime);
if (rv.async) await rv.value;
await releaseImplicitLocks();
continue;
}
} else {
/**
For browsers without Atomics.waitAsync(), we require
the legacy implementation. Browser versions where
waitAsync() arrived:
Chrome: 90 (2021-04-13)
Firefox: 145 (2025-11-11)
Safari: 16.4 (2023-03-27)
The "opfs" VFS was not born until Chrome was somewhere in
the v104-108 range (Summer/Autumn 2022) and did not work
with Safari < v17 (2023-09-18) due to a WebKit bug which
restricted OPFS access from sub-Workers.
The waitAsync() counterpart of this block can be used by
both "opfs" and "opfs-wl", whereas this block can only be
used by "opfs". Performance comparisons between the two
in high-contention tests have been indecisive.
*/
if ("not-equal" !== Atomics.wait(state.sabOPView, slotWhichOp, 0, state.asyncIdleWaitTime)) {
await releaseImplicitLocks();
continue;
}
opId = Atomics.load(state.sabOPView, slotWhichOp);
}
Atomics.store(opView, slotWhichOp, 0);
await (f.opHandlers[opId]?.f ?? toss("No waitLoop handler for whichOp #", opId))(...state.s11n.deserialize(true) || []);
} catch (e) {
error("in waitLoop():", e);
}
};
navigator.storage.getDirectory().then(function(d) {
state.rootDir = d;
globalThis.onmessage = function({ data }) {
switch (data.type) {
case "opfs-async-init": {
const opt = data.args;
for (const k in opt) state[k] = opt[k];
state.verbose = opt.verbose ?? 1;
state.sabOPView = new Int32Array(state.sabOP);
state.sabFileBufView = new Uint8Array(state.sabIO, 0, state.fileBufferSize);
state.sabS11nView = new Uint8Array(state.sabIO, state.sabS11nOffset, state.sabS11nSize);
Object.keys(vfsAsyncImpls).forEach((k) => {
if (!Number.isFinite(state.opIds[k])) toss("Maintenance required: missing state.opIds[", k, "]");
});
initS11n();
log("init state", state);
wPost("opfs-async-inited");
waitLoop();
break;
}
case "opfs-async-restart":
if (flagAsyncShutdown) {
warn("Restarting after opfs-async-shutdown. Might or might not work.");
flagAsyncShutdown = false;
waitLoop();
}
break;
}
};
wPost("opfs-async-loaded");
}).catch((e) => error("error initializing OPFS asyncer:", e));
};
if (globalThis.window === globalThis) wPost("opfs-unavailable", "This code cannot run from the main thread.", "Load it as a Worker from a separate Worker.");
else if (!globalThis.SharedArrayBuffer) wPost("opfs-unavailable", "Missing SharedArrayBuffer API.", "The server must emit the COOP/COEP response headers to enable that.");
else if (!globalThis.Atomics) wPost("opfs-unavailable", "Missing Atomics API.", "The server must emit the COOP/COEP response headers to enable that.");
else if (isWebLocker && !globalThis.Atomics.waitAsync) wPost("opfs-unavailable", "Missing required Atomics.waitSync() for " + vfsName);
else if (!globalThis.FileSystemHandle || !globalThis.FileSystemDirectoryHandle || !globalThis.FileSystemFileHandle?.prototype?.createSyncAccessHandle || !navigator?.storage?.getDirectory) wPost("opfs-unavailable", "Missing required OPFS APIs.");
else installAsyncProxy();
//#endregion
})();