* Enabled the Emscripten IDBFS virtual filesystem driver. This filesystem type can be used to persist data in web browser storage across page reloads. This filesystem type must be used with the `PostMessage` communication channel (#56, #442).

MAIN_LDFLAGS += -lworkerfs.js -lnodefs.js -lidbfs.js

RoxygenNote: 7.3.1

export(syncfs)

} else if (tolower(type) == "idbfs") {

invisible(.Call(ffi_mount_idbfs, mountpoint))

syncfs <- function(populate) {

invisible(.Call(ffi_syncfs, populate))

}

extern SEXP ffi_mount_idbfs(SEXP);

extern SEXP ffi_syncfs(SEXP);

{ "ffi_mount_idbfs", (DL_FUNC) &ffi_mount_idbfs, 1},

{ "ffi_syncfs", (DL_FUNC) &ffi_syncfs, 1},

#define CHECK_LOGICAL(arg) \

if (!Rf_isLogical(arg) || LENGTH(arg) != 1) { \

Rf_error("`" #arg "` must be a logical."); \

} \

if (LOGICAL(arg)[0] == NA_LOGICAL){ \

Rf_error("`" #arg "` can't be `NA`."); \

}

SEXP ffi_mount_idbfs(SEXP mountpoint) {

#ifdef __EMSCRIPTEN__

CHECK_STRING(mountpoint);

EM_ASM({

// Stop if we're not able to use a IDBFS filesystem object

if (typeof IN_NODE === 'boolean' && IN_NODE === true) {

const msg = Module.allocateUTF8OnStack(

'The `IDBFS` filesystem object can only be used when running in a web browser.'

);

Module._Rf_error(msg);

}

const mountpoint = UTF8ToString($0);

try {

Module.FS.mount(Module.FS.filesystems.IDBFS, {}, mountpoint);

} catch (e) {

let msg = e.message;

if (e.name === "ErrnoError" && e.errno === 10) {

const dir = Module.UTF8ToString($0);

msg = "Unable to mount directory, `" + dir + "` is already mounted.";

}

Module._Rf_error(Module.allocateUTF8OnStack(msg));

}

}, R_CHAR(STRING_ELT(mountpoint, 0)));

return R_NilValue;

Rf_error("Function must be running under Emscripten.");

}

SEXP ffi_syncfs(SEXP populate) {

#ifdef __EMSCRIPTEN__

CHECK_LOGICAL(populate);

EM_ASM({ Module.FS.syncfs($0, () => {}) }, LOGICAL(populate)[0]);

return R_NilValue;

Rf_error("Function must be running under Emscripten.");

}

Emscripten's API allows for several types of virtual filesystem, depending on the execution environment. The following filesystems are available for use with webR:

| `WORKERFS` | Mount Emscripten filesystem images. | &#x2705; | &#x2705;[^workerfs] |

| `IDBFS` | Browser-based persistent storage using the [IndexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). | &#x2705;[^idbfs] | &#x274C; |

[^workerfs]: Be aware of the current GitHub issue [#328](https://github.com/r-wasm/webr/issues/328).

[^idbfs]: Using the `PostMessage` [communication channel](communication.qmd) only.

Emscripten filesystem images can be mounted using the `WORKERFS` filesystem type.

The `NODEFS` filesystem type maps directories that exist on the host machine so that they are accessible in the WebAssembly process.

:::

When using webR in a web browser, an [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)-based persistent storage space can be mounted using the `IDBFS` filesystem type.

::: {.callout-warning}

Due to the way webR blocks for input in the worker thread, the `IDBFS` filesystem type **does not work** when using the `SharedArrayBuffer` communication channel. WebR must be configured to use the `PostMessage` communication channel to use `IDBFS` persistent storage.

:::

First, create a directory to contain the IndexedDB filesystem, then use either the JavaScript or R mount API with type `"IDBFS"`.

::: {.panel-tabset}

``` javascript

await webR.FS.mkdir('/data');

await webR.FS.mount('IDBFS', {}, '/data');

await webR.FS.syncfs(true);

```{r eval=FALSE}

After mounting the filesystem using [`mount()`](api/r.html#mount), the [`syncfs()`](api/r.html#syncfs) function should been invoked with its `populate` argument set to `true`. This extra step is **required** to initialise the virtual filesystem with any previously existing data files in the browser's IndexedDB storage. Without it, the filesystem will always be initially mounted as an empty directory.

For more information, see the Emscripten FS API [`IDBFS` and `FS.syncfs()`](https://emscripten.org/docs/api_reference/Filesystem-API.html#filesystem-api-idbfs) documentation.

The `syncfs()` function should be invoked with its `populate` argument set to `false` to persist the current state of the filesystem to the browser's IndexedDB storage.

::: {.panel-tabset}

``` javascript

await webR.FS.syncfs(false);

```{r eval=FALSE}

:::

After writing to the virtual filesystem you should be sure to invoke `syncfs(false)` before the web page containing webR is closed to ensure that the filesystem data is flushed and written to the IndexedDB-based persistent storage.

::: {.callout-warning}

Operations performed using IndexedDB are done asynchronously. If you are mounting `IDBFS` filesystems and accessing data non-interactively you should use the JavaScript API and be sure to wait for the `Promise` returned by `webR.FS.syncfs(false)` to resolve before continuing, for example by using the `await` keyword.

In a future version of webR the `webr::syncfs()` function will similarly return a Promise-like object.

:::

Filesystem data stored in an IndexedDB database can only be accessed within the current [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin), loosely defined as the current web page's host domain and port.

The way in which web browsers decide how much storage space to allocate for data and what to remove when limits are reached differs between browsers and is not always simple to calculate. Be aware of browser [storage quotas and eviction criteria](https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria) and note that data stored in an `IDBFS` filesystem type is stored only on a "best-effort" basis. It can be removed by the browser at any time, autonomously or by the user interacting through the browser's UI.

In private browsing mode, for example, stored data is usually deleted when the private session ends.

export interface FSSyncfsMessage extends Message {

type: 'syncfs';

data: { populate: boolean };

FSSyncfsMessage,

export type FSType = 'NODEFS' | 'WORKERFS' | 'IDBFS';

syncfs: async (populate: boolean): Promise<void> => {

const msg: FSSyncfsMessage = { type: 'syncfs', data: { populate } };

await this.#chan.request(msg);

},