feat(fs): add plugin (#308)

Cargo.lock

@@ -4552,17 +4552,6 @@ dependencies = [
  "thiserror",
 ]
 
-[[package]]
-name = "tauri-plugin-fs-extra"
-version = "0.1.0"
-dependencies = [
- "log",
- "serde",
- "serde_json",
- "tauri",
- "thiserror",
-]
-
 [[package]]
 name = "tauri-plugin-fs-watch"
 version = "0.1.0"

Cargo.toml

@@ -1,5 +1,6 @@
 [workspace]
 members = ["plugins/*"]
+exclude = ["plugins/fs"]
 resolver = "2"
 
 [workspace.dependencies]

plugins/fs-extra/Cargo.toml

@@ -1,17 +0,0 @@
-[package]
-name = "tauri-plugin-fs-extra"
-version = "0.1.0"
-description = "Additional file system methods not included in the core API."
-authors.workspace = true
-license.workspace = true
-edition.workspace = true
-rust-version.workspace = true
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
-[dependencies]
-serde.workspace = true
-serde_json.workspace = true
-tauri.workspace = true
-log.workspace = true
-thiserror.workspace = true

plugins/fs-extra/guest-js/index.ts

@@ -1,130 +0,0 @@
-// Copyright 2019-2021 Tauri Programme within The Commons Conservancy
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-License-Identifier: MIT
-
-import { invoke } from "@tauri-apps/api/tauri";
-
-export interface Permissions {
-  /**
-   * `true` if these permissions describe a readonly (unwritable) file.
-   */
-  readonly: boolean;
-  /**
-   * The underlying raw `st_mode` bits that contain the standard Unix permissions for this file.
-   */
-  mode: number | undefined;
-}
-
-/**
- * Metadata information about a file.
- * This structure is returned from the `metadata` function or method
- * and represents known metadata about a file such as its permissions, size, modification times, etc.
- */
-export interface Metadata {
-  /**
-   * The last access time of this metadata.
-   */
-  accessedAt: Date;
-  /**
-   * The creation time listed in this metadata.
-   */
-  createdAt: Date;
-  /**
-   * The last modification time listed in this metadata.
-   */
-  modifiedAt: Date;
-  /**
-   * `true` if this metadata is for a directory.
-   */
-  isDir: boolean;
-  /**
-   * `true` if this metadata is for a regular file.
-   */
-  isFile: boolean;
-  /**
-   * `true` if this metadata is for a symbolic link.
-   */
-  isSymlink: boolean;
-  /**
-   * The size of the file, in bytes, this metadata is for.
-   */
-  size: number;
-  /**
-   * The permissions of the file this metadata is for.
-   */
-  permissions: Permissions;
-  /**
-   * The ID of the device containing the file. Only available on Unix.
-   */
-  dev: number | undefined;
-  /**
-   * The inode number. Only available on Unix.
-   */
-  ino: number | undefined;
-  /**
-   * The rights applied to this file. Only available on Unix.
-   */
-  mode: number | undefined;
-  /**
-   * The number of hard links pointing to this file. Only available on Unix.
-   */
-  nlink: number | undefined;
-  /**
-   * The user ID of the owner of this file. Only available on Unix.
-   */
-  uid: number | undefined;
-  /**
-   * The group ID of the owner of this file. Only available on Unix.
-   */
-  gid: number | undefined;
-  /**
-   * The device ID of this file (if it is a special one). Only available on Unix.
-   */
-  rdev: number | undefined;
-  /**
-   * The block size for filesystem I/O. Only available on Unix.
-   */
-  blksize: number | undefined;
-  /**
-   * The number of blocks allocated to the file, in 512-byte units. Only available on Unix.
-   */
-  blocks: number | undefined;
-}
-
-interface BackendMetadata {
-  accessedAtMs: number;
-  createdAtMs: number;
-  modifiedAtMs: number;
-  isDir: boolean;
-  isFile: boolean;
-  isSymlink: boolean;
-  size: number;
-  permissions: Permissions;
-  dev: number | undefined;
-  ino: number | undefined;
-  mode: number | undefined;
-  nlink: number | undefined;
-  uid: number | undefined;
-  gid: number | undefined;
-  rdev: number | undefined;
-  blksize: number | undefined;
-  blocks: number | undefined;
-}
-
-export async function metadata(path: string): Promise<Metadata> {
-  return await invoke<BackendMetadata>("plugin:fs-extra|metadata", {
-    path,
-  }).then((metadata) => {
-    const { accessedAtMs, createdAtMs, modifiedAtMs, ...data } = metadata;
-    return {
-      accessedAt: new Date(accessedAtMs),
-      createdAt: new Date(createdAtMs),
-      modifiedAt: new Date(modifiedAtMs),
-      ...data,
-    };
-  });
-}
-
-export async function exists(path: string): Promise<boolean> {
-  return await invoke("plugin:fs-extra|exists", { path });
-}

plugins/fs-extra/src/lib.rs

@@ -1,132 +0,0 @@
-// Copyright 2019-2021 Tauri Programme within The Commons Conservancy
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-License-Identifier: MIT
-
-use serde::{ser::Serializer, Serialize};
-use tauri::{
-    command,
-    plugin::{Builder as PluginBuilder, TauriPlugin},
-    Runtime,
-};
-
-use std::{
-    path::PathBuf,
-    time::{SystemTime, UNIX_EPOCH},
-};
-
-#[cfg(unix)]
-use std::os::unix::fs::{MetadataExt, PermissionsExt};
-#[cfg(windows)]
-use std::os::windows::fs::MetadataExt;
-
-type Result<T> = std::result::Result<T, Error>;
-
-#[derive(Debug, thiserror::Error)]
-pub enum Error {
-    #[error(transparent)]
-    Io(#[from] std::io::Error),
-}
-
-impl Serialize for Error {
-    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
-    where
-        S: Serializer,
-    {
-        serializer.serialize_str(self.to_string().as_ref())
-    }
-}
-
-#[derive(Serialize)]
-#[serde(rename_all = "camelCase")]
-struct Permissions {
-    readonly: bool,
-    #[cfg(unix)]
-    mode: u32,
-}
-
-#[cfg(unix)]
-#[derive(Serialize)]
-#[serde(rename_all = "camelCase")]
-struct UnixMetadata {
-    dev: u64,
-    ino: u64,
-    mode: u32,
-    nlink: u64,
-    uid: u32,
-    gid: u32,
-    rdev: u64,
-    blksize: u64,
-    blocks: u64,
-}
-
-#[derive(Serialize)]
-#[serde(rename_all = "camelCase")]
-struct Metadata {
-    accessed_at_ms: u64,
-    created_at_ms: u64,
-    modified_at_ms: u64,
-    is_dir: bool,
-    is_file: bool,
-    is_symlink: bool,
-    size: u64,
-    permissions: Permissions,
-    #[cfg(unix)]
-    #[serde(flatten)]
-    unix: UnixMetadata,
-    #[cfg(windows)]
-    file_attributes: u32,
-}
-
-fn system_time_to_ms(time: std::io::Result<SystemTime>) -> u64 {
-    time.map(|t| {
-        let duration_since_epoch = t.duration_since(UNIX_EPOCH).unwrap();
-        duration_since_epoch.as_millis() as u64
-    })
-    .unwrap_or_default()
-}
-
-#[command]
-async fn metadata(path: PathBuf) -> Result<Metadata> {
-    let metadata = std::fs::metadata(path)?;
-    let file_type = metadata.file_type();
-    let permissions = metadata.permissions();
-    Ok(Metadata {
-        accessed_at_ms: system_time_to_ms(metadata.accessed()),
-        created_at_ms: system_time_to_ms(metadata.created()),
-        modified_at_ms: system_time_to_ms(metadata.modified()),
-        is_dir: file_type.is_dir(),
-        is_file: file_type.is_file(),
-        is_symlink: file_type.is_symlink(),
-        size: metadata.len(),
-        permissions: Permissions {
-            readonly: permissions.readonly(),
-            #[cfg(unix)]
-            mode: permissions.mode(),
-        },
-        #[cfg(unix)]
-        unix: UnixMetadata {
-            dev: metadata.dev(),
-            ino: metadata.ino(),
-            mode: metadata.mode(),
-            nlink: metadata.nlink(),
-            uid: metadata.uid(),
-            gid: metadata.gid(),
-            rdev: metadata.rdev(),
-            blksize: metadata.blksize(),
-            blocks: metadata.blocks(),
-        },
-        #[cfg(windows)]
-        file_attributes: metadata.file_attributes(),
-    })
-}
-
-#[command]
-async fn exists(path: PathBuf) -> bool {
-    path.exists()
-}
-
-pub fn init<R: Runtime>() -> TauriPlugin<R> {
-    PluginBuilder::new("fs-extra")
-        .invoke_handler(tauri::generate_handler![exists, metadata])
-        .build()
-}

plugins/fs/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "tauri-plugin-fs"
+version = "0.1.0"
+description = "Access the file system."
+edition = "2021"
+#authors.workspace = true
+#license.workspace = true
+#edition.workspace = true
+#rust-version.workspace = true
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+#serde.workspace = true
+#serde_json.workspace = true
+#tauri.workspace = true
+#log.workspace = true
+#thiserror.workspace = true
+serde = "1"
+thiserror = "1"
+tauri = { git = "https://github.com/tauri-apps/tauri", branch = "next" }
+anyhow = "1"

plugins/fs/README.md

@@ -1,6 +1,6 @@
-![tauri-plugin-fs-extra](banner.png)
+![tauri-plugin-fs](banner.png)
 
-Additional file system methods not included in the core API.
+Access the file system.
 
 ## Install
 
@@ -18,7 +18,7 @@ Install the Core plugin by adding the following to your `Cargo.toml` file:
 
 ```toml
 [dependencies]
-tauri-plugin-fs-extra = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" }
+tauri-plugin-fs = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" }
 ```
 
 You can install the JavaScript Guest bindings using your preferred JavaScript package manager:
@@ -26,11 +26,11 @@ You can install the JavaScript Guest bindings using your preferred JavaScript pa
 > Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use.
 
 ```sh
-pnpm add https://github.com/tauri-apps/tauri-plugin-fs-extra
+pnpm add https://github.com/tauri-apps/tauri-plugin-fs
 # or
-npm add https://github.com/tauri-apps/tauri-plugin-fs-extra
+npm add https://github.com/tauri-apps/tauri-plugin-fs
 # or
-yarn add https://github.com/tauri-apps/tauri-plugin-fs-extra
+yarn add https://github.com/tauri-apps/tauri-plugin-fs
 ```
 
 ## Usage
@@ -42,7 +42,7 @@ First you need to register the core plugin with Tauri:
 ```rust
 fn main() {
     tauri::Builder::default()
-        .plugin(tauri_plugin_fs_extra::init())
+        .plugin(tauri_plugin_fs::init())
         .run(tauri::generate_context!())
         .expect("error while running tauri application");
 }
@@ -51,7 +51,7 @@ fn main() {
 Afterwards all the plugin's APIs are available through the JavaScript guest bindings:
 
 ```javascript
-import { metadata } from "tauri-plugin-fs-extra-api";
+import { metadata } from "tauri-plugin-fs-api";
 
 await metadata("/path/to/file");
 ```

plugins/fs/guest-js/index.ts

@@ -0,0 +1,691 @@
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+/**
+ * Access the file system.
+ *
+ * This package is also accessible with `window.__TAURI__.fs` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
+ *
+ * The APIs must be added to [`tauri.allowlist.fs`](https://tauri.app/v1/api/config/#allowlistconfig.fs) in `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "fs": {
+ *         "all": true, // enable all FS APIs
+ *         "readFile": true,
+ *         "writeFile": true,
+ *         "readDir": true,
+ *         "copyFile": true,
+ *         "createDir": true,
+ *         "removeDir": true,
+ *         "removeFile": true,
+ *         "renameFile": true,
+ *         "metadata": true,
+ *         "exists": true
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
+ *
+ * ## Security
+ *
+ * This module prevents path traversal, not allowing absolute paths or parent dir components
+ * (i.e. "/usr/path/to/file" or "../path/to/file" paths are not allowed).
+ * Paths accessed with this API must be relative to one of the {@link BaseDirectory | base directories}
+ * so if you need access to arbitrary filesystem paths, you must write such logic on the core layer instead.
+ *
+ * The API has a scope configuration that forces you to restrict the paths that can be accessed using glob patterns.
+ *
+ * The scope configuration is an array of glob patterns describing folder paths that are allowed.
+ * For instance, this scope configuration only allows accessing files on the
+ * *databases* folder of the {@link path.appDataDir | $APPDATA directory}:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "fs": {
+ *         "scope": ["$APPDATA/databases/*"]
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Notice the use of the `$APPDATA` variable. The value is injected at runtime, resolving to the {@link path.appDataDir | app data directory}.
+ * The available variables are:
+ * {@link path.appConfigDir | `$APPCONFIG`}, {@link path.appDataDir | `$APPDATA`}, {@link path.appLocalDataDir | `$APPLOCALDATA`},
+ * {@link path.appCacheDir | `$APPCACHE`}, {@link path.appLogDir | `$APPLOG`},
+ * {@link path.audioDir | `$AUDIO`}, {@link path.cacheDir | `$CACHE`}, {@link path.configDir | `$CONFIG`}, {@link path.dataDir | `$DATA`},
+ * {@link path.localDataDir | `$LOCALDATA`}, {@link path.desktopDir | `$DESKTOP`}, {@link path.documentDir | `$DOCUMENT`},
+ * {@link path.downloadDir | `$DOWNLOAD`}, {@link path.executableDir | `$EXE`}, {@link path.fontDir | `$FONT`}, {@link path.homeDir | `$HOME`},
+ * {@link path.pictureDir | `$PICTURE`}, {@link path.publicDir | `$PUBLIC`}, {@link path.runtimeDir | `$RUNTIME`},
+ * {@link path.templateDir | `$TEMPLATE`}, {@link path.videoDir | `$VIDEO`}, {@link path.resourceDir | `$RESOURCE`},
+ * {@link os.tempdir | `$TEMP`}.
+ *
+ * Trying to execute any API with a URL not configured on the scope results in a promise rejection due to denied access.
+ *
+ * Note that this scope applies to **all** APIs on this module.
+ *
+ * @module
+ */
+
+import { invoke } from "@tauri-apps/api/tauri";
+
+interface Permissions {
+  /**
+   * `true` if these permissions describe a readonly (unwritable) file.
+   */
+  readonly: boolean;
+  /**
+   * The underlying raw `st_mode` bits that contain the standard Unix permissions for this file.
+   */
+  mode: number | undefined;
+}
+
+/**
+ * Metadata information about a file.
+ * This structure is returned from the `metadata` function or method
+ * and represents known metadata about a file such as its permissions, size, modification times, etc.
+ */
+interface Metadata {
+  /**
+   * The last access time of this metadata.
+   */
+  accessedAt: Date;
+  /**
+   * The creation time listed in this metadata.
+   */
+  createdAt: Date;
+  /**
+   * The last modification time listed in this metadata.
+   */
+  modifiedAt: Date;
+  /**
+   * `true` if this metadata is for a directory.
+   */
+  isDir: boolean;
+  /**
+   * `true` if this metadata is for a regular file.
+   */
+  isFile: boolean;
+  /**
+   * `true` if this metadata is for a symbolic link.
+   */
+  isSymlink: boolean;
+  /**
+   * The size of the file, in bytes, this metadata is for.
+   */
+  size: number;
+  /**
+   * The permissions of the file this metadata is for.
+   */
+  permissions: Permissions;
+  /**
+   * The ID of the device containing the file. Only available on Unix.
+   */
+  dev: number | undefined;
+  /**
+   * The inode number. Only available on Unix.
+   */
+  ino: number | undefined;
+  /**
+   * The rights applied to this file. Only available on Unix.
+   */
+  mode: number | undefined;
+  /**
+   * The number of hard links pointing to this file. Only available on Unix.
+   */
+  nlink: number | undefined;
+  /**
+   * The user ID of the owner of this file. Only available on Unix.
+   */
+  uid: number | undefined;
+  /**
+   * The group ID of the owner of this file. Only available on Unix.
+   */
+  gid: number | undefined;
+  /**
+   * The device ID of this file (if it is a special one). Only available on Unix.
+   */
+  rdev: number | undefined;
+  /**
+   * The block size for filesystem I/O. Only available on Unix.
+   */
+  blksize: number | undefined;
+  /**
+   * The number of blocks allocated to the file, in 512-byte units. Only available on Unix.
+   */
+  blocks: number | undefined;
+}
+
+interface BackendMetadata {
+  accessedAtMs: number;
+  createdAtMs: number;
+  modifiedAtMs: number;
+  isDir: boolean;
+  isFile: boolean;
+  isSymlink: boolean;
+  size: number;
+  permissions: Permissions;
+  dev: number | undefined;
+  ino: number | undefined;
+  mode: number | undefined;
+  nlink: number | undefined;
+  uid: number | undefined;
+  gid: number | undefined;
+  rdev: number | undefined;
+  blksize: number | undefined;
+  blocks: number | undefined;
+}
+
+// TODO: pull BaseDirectory from @tauri-apps/api/path
+/**
+ * @since 1.0.0
+ */
+enum BaseDirectory {
+  Audio = 1,
+  Cache,
+  Config,
+  Data,
+  LocalData,
+  Document,
+  Download,
+  Picture,
+  Public,
+  Video,
+  Resource,
+  Temp,
+  AppConfig,
+  AppData,
+  AppLocalData,
+  AppCache,
+  AppLog,
+
+  Desktop,
+  Executable,
+  Font,
+  Home,
+  Runtime,
+  Template
+}
+
+/**
+ * @since 1.0.0
+ */
+interface FsOptions {
+  dir?: BaseDirectory
+  // note that adding fields here needs a change in the writeBinaryFile check
+}
+
+/**
+ * @since 1.0.0
+ */
+interface FsDirOptions {
+  dir?: BaseDirectory
+  recursive?: boolean
+}
+
+/**
+ * Options object used to write a UTF-8 string to a file.
+ *
+ * @since 1.0.0
+ */
+interface FsTextFileOption {
+  /** Path to the file to write. */
+  path: string
+  /** The UTF-8 string to write to the file. */
+  contents: string
+}
+
+type BinaryFileContents = Iterable<number> | ArrayLike<number> | ArrayBuffer
+
+/**
+ * Options object used to write a binary data to a file.
+ *
+ * @since 1.0.0
+ */
+interface FsBinaryFileOption {
+  /** Path to the file to write. */
+  path: string
+  /** The byte array contents. */
+  contents: BinaryFileContents
+}
+
+/**
+ * @since 1.0.0
+ */
+interface FileEntry {
+  path: string
+  /**
+   * Name of the directory/file
+   * can be null if the path terminates with `..`
+   */
+  name?: string
+  /** Children of this entry if it's a directory; null otherwise */
+  children?: FileEntry[]
+}
+
+/**
+ * Reads a file as an UTF-8 encoded string.
+ * @example
+ * ```typescript
+ * import { readTextFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Read the text file in the `$APPCONFIG/app.conf` path
+ * const contents = await readTextFile('app.conf', { dir: BaseDirectory.AppConfig });
+ * ```
+ *
+ * @since 1.0.0
+ */
+async function readTextFile(
+  filePath: string,
+  options: FsOptions = {}
+): Promise<string> {
+  return await invoke("plugin:fs|read_text_file", {
+    path: filePath,
+    options
+  })
+}
+
+/**
+ * Reads a file as byte array.
+ * @example
+ * ```typescript
+ * import { readBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Read the image file in the `$RESOURCEDIR/avatar.png` path
+ * const contents = await readBinaryFile('avatar.png', { dir: BaseDirectory.Resource });
+ * ```
+ *
+ * @since 1.0.0
+ */
+async function readBinaryFile(
+  filePath: string,
+  options: FsOptions = {}
+): Promise<Uint8Array> {
+  const arr = await invoke<number[]>("plugin:fs|read_file", {
+    path: filePath,
+    options
+  })
+
+  return Uint8Array.from(arr)
+}
+
+/**
+ * Writes a UTF-8 text file.
+ * @example
+ * ```typescript
+ * import { writeTextFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Write a text file to the `$APPCONFIG/app.conf` path
+ * await writeTextFile('app.conf', 'file contents', { dir: BaseDirectory.AppConfig });
+ * ```
+ *
+ * @since 1.0.0
+ */
+async function writeTextFile(
+  path: string,
+  contents: string,
+  options?: FsOptions
+): Promise<void>
+
+/**
+ * Writes a UTF-8 text file.
+ * @example
+ * ```typescript
+ * import { writeTextFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Write a text file to the `$APPCONFIG/app.conf` path
+ * await writeTextFile({ path: 'app.conf', contents: 'file contents' }, { dir: BaseDirectory.AppConfig });
+ * ```
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function writeTextFile(
+  file: FsTextFileOption,
+  options?: FsOptions
+): Promise<void>
+
+/**
+ * Writes a UTF-8 text file.
+ *
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function writeTextFile(
+  path: string | FsTextFileOption,
+  contents?: string | FsOptions,
+  options?: FsOptions
+): Promise<void> {
+  if (typeof options === 'object') {
+    Object.freeze(options)
+  }
+  if (typeof path === 'object') {
+    Object.freeze(path)
+  }
+
+  const file: FsTextFileOption = { path: '', contents: '' }
+  let fileOptions: FsOptions | undefined = options
+  if (typeof path === 'string') {
+    file.path = path
+  } else {
+    file.path = path.path
+    file.contents = path.contents
+  }
+
+  if (typeof contents === 'string') {
+    file.contents = contents ?? ''
+  } else {
+    fileOptions = contents
+  }
+
+  return await invoke("plugin:fs|write_file", {
+    path: file.path,
+    contents: Array.from(new TextEncoder().encode(file.contents)),
+    options: fileOptions
+  })
+}
+
+/**
+ * Writes a byte array content to a file.
+ * @example
+ * ```typescript
+ * import { writeBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Write a binary file to the `$APPDATA/avatar.png` path
+ * await writeBinaryFile('avatar.png', new Uint8Array([]), { dir: BaseDirectory.AppData });
+ * ```
+ *
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function writeBinaryFile(
+  path: string,
+  contents: BinaryFileContents,
+  options?: FsOptions
+): Promise<void>
+
+/**
+ * Writes a byte array content to a file.
+ * @example
+ * ```typescript
+ * import { writeBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Write a binary file to the `$APPDATA/avatar.png` path
+ * await writeBinaryFile({ path: 'avatar.png', contents: new Uint8Array([]) }, { dir: BaseDirectory.AppData });
+ * ```
+ *
+ * @param file The object containing the file path and contents.
+ * @param options Configuration object.
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function writeBinaryFile(
+  file: FsBinaryFileOption,
+  options?: FsOptions
+): Promise<void>
+
+/**
+ * Writes a byte array content to a file.
+ *
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function writeBinaryFile(
+  path: string | FsBinaryFileOption,
+  contents?: BinaryFileContents | FsOptions,
+  options?: FsOptions
+): Promise<void> {
+  if (typeof options === 'object') {
+    Object.freeze(options)
+  }
+  if (typeof path === 'object') {
+    Object.freeze(path)
+  }
+
+  const file: FsBinaryFileOption = { path: '', contents: [] }
+  let fileOptions: FsOptions | undefined = options
+  if (typeof path === 'string') {
+    file.path = path
+  } else {
+    file.path = path.path
+    file.contents = path.contents
+  }
+
+  if (contents && 'dir' in contents) {
+    fileOptions = contents
+  } else if (typeof path === 'string') {
+    // @ts-expect-error in this case `contents` is always a BinaryFileContents
+    file.contents = contents ?? []
+  }
+
+  return await invoke("plugin:fs|write_binary_file", {
+    path: file.path,
+    contents: Array.from(
+      file.contents instanceof ArrayBuffer
+        ? new Uint8Array(file.contents)
+        : file.contents
+    ),
+    options: fileOptions
+  })
+}
+
+/**
+ * List directory files.
+ * @example
+ * ```typescript
+ * import { readDir, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Reads the `$APPDATA/users` directory recursively
+ * const entries = await readDir('users', { dir: BaseDirectory.AppData, recursive: true });
+ *
+ * function processEntries(entries) {
+ *   for (const entry of entries) {
+ *     console.log(`Entry: ${entry.path}`);
+ *     if (entry.children) {
+ *       processEntries(entry.children)
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+async function readDir(
+  dir: string,
+  options: FsDirOptions = {}
+): Promise<FileEntry[]> {
+  return await invoke("plugin:fs|read_dir", {
+    path: dir,
+    options
+  })
+}
+
+/**
+ * Creates a directory.
+ * If one of the path's parent components doesn't exist
+ * and the `recursive` option isn't set to true, the promise will be rejected.
+ * @example
+ * ```typescript
+ * import { createDir, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Create the `$APPDATA/users` directory
+ * await createDir('users', { dir: BaseDirectory.AppData, recursive: true });
+ * ```
+ *
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function createDir(
+  dir: string,
+  options: FsDirOptions = {}
+): Promise<void> {
+  return await invoke("plugin:fs|create_dir", {
+    path: dir,
+    options
+  })
+}
+
+/**
+ * Removes a directory.
+ * If the directory is not empty and the `recursive` option isn't set to true, the promise will be rejected.
+ * @example
+ * ```typescript
+ * import { removeDir, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Remove the directory `$APPDATA/users`
+ * await removeDir('users', { dir: BaseDirectory.AppData });
+ * ```
+ *
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function removeDir(
+  dir: string,
+  options: FsDirOptions = {}
+): Promise<void> {
+  return await invoke("plugin:fs|remove_dir", {
+    path: dir,
+    options
+  })
+}
+
+/**
+ * Copies a file to a destination.
+ * @example
+ * ```typescript
+ * import { copyFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Copy the `$APPCONFIG/app.conf` file to `$APPCONFIG/app.conf.bk`
+ * await copyFile('app.conf', 'app.conf.bk', { dir: BaseDirectory.AppConfig });
+ * ```
+ *
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function copyFile(
+  source: string,
+  destination: string,
+  options: FsOptions = {}
+): Promise<void> {
+  return await invoke("plugin:fs|copy_file", {
+    source,
+    destination,
+    options
+  })
+}
+
+/**
+ * Removes a file.
+ * @example
+ * ```typescript
+ * import { removeFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Remove the `$APPConfig/app.conf` file
+ * await removeFile('app.conf', { dir: BaseDirectory.AppConfig });
+ * ```
+ *
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function removeFile(
+  file: string,
+  options: FsOptions = {}
+): Promise<void> {
+  return await invoke("plugin:fs|remove_file", {
+    path: file,
+    options
+  })
+}
+
+/**
+ * Renames a file.
+ * @example
+ * ```typescript
+ * import { renameFile, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Rename the `$APPDATA/avatar.png` file
+ * await renameFile('avatar.png', 'deleted.png', { dir: BaseDirectory.AppData });
+ * ```
+ *
+ * @returns A promise indicating the success or failure of the operation.
+ *
+ * @since 1.0.0
+ */
+async function renameFile(
+  oldPath: string,
+  newPath: string,
+  options: FsOptions = {}
+): Promise<void> {
+  return await invoke("plugin:fs|rename_file", {
+    oldPath,
+    newPath,
+    options
+
+  })
+}
+
+/**
+ * Check if a path exists.
+ * @example
+ * ```typescript
+ * import { exists, BaseDirectory } from '@tauri-apps/api/fs';
+ * // Check if the `$APPDATA/avatar.png` file exists
+ * await exists('avatar.png', { dir: BaseDirectory.AppData });
+ * ```
+ *
+ * @since 1.0.0
+ */
+async function exists(path: string): Promise<boolean> {
+  return await invoke("plugin:fs|exists", { path });
+}
+
+/**
+ * Returns the metadata for the given path.
+ * 
+ * @since 1.0.0
+ */
+async function metadata(path: string): Promise<Metadata> {
+  return await invoke<BackendMetadata>("plugin:fs|metadata", {
+    path,
+  }).then((metadata) => {
+    const { accessedAtMs, createdAtMs, modifiedAtMs, ...data } = metadata;
+    return {
+      accessedAt: new Date(accessedAtMs),
+      createdAt: new Date(createdAtMs),
+      modifiedAt: new Date(modifiedAtMs),
+      ...data,
+    };
+  });
+}
+
+export type {
+  FsOptions,
+  FsDirOptions,
+  FsTextFileOption,
+  BinaryFileContents,
+  FsBinaryFileOption,
+  FileEntry,
+  Permissions,
+  Metadata,
+}
+
+export {
+  BaseDirectory,
+  BaseDirectory as Dir,
+  readTextFile,
+  readBinaryFile,
+  writeTextFile,
+  writeTextFile as writeFile,
+  writeBinaryFile,
+  readDir,
+  createDir,
+  removeDir,
+  copyFile,
+  removeFile,
+  renameFile,
+  exists,
+  metadata
+}

plugins/fs/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "tauri-plugin-fs-extra-api",
+  "name": "tauri-plugin-fs-api",
   "version": "0.0.0",
-  "description": "Additional file system methods not included in the core API.",
+  "description": "Access the file system.",
   "license": "MIT or APACHE-2.0",
   "authors": [
     "Tauri Programme within The Commons Conservancy"

plugins/fs/src/commands.rs

@@ -0,0 +1,394 @@
+use anyhow::Context;
+use serde::{Deserialize, Serialize, Serializer};
+use tauri::{
+    path::{BaseDirectory, SafePathBuf},
+    FsScope, Manager, Runtime, Window,
+};
+
+#[cfg(unix)]
+use std::os::unix::fs::{MetadataExt, PermissionsExt};
+#[cfg(windows)]
+use std::os::windows::fs::MetadataExt;
+use std::{
+    fs::{self, symlink_metadata, File},
+    io::Write,
+    path::{Path, PathBuf},
+    time::{SystemTime, UNIX_EPOCH},
+};
+
+use crate::{Error, Result};
+
+#[derive(Debug, thiserror::Error)]
+pub enum CommandError {
+    #[error(transparent)]
+    Anyhow(#[from] anyhow::Error),
+    #[error(transparent)]
+    Plugin(#[from] Error),
+}
+
+impl Serialize for CommandError {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_str(self.to_string().as_ref())
+    }
+}
+
+type CommandResult<T> = std::result::Result<T, CommandError>;
+
+/// The options for the directory functions on the file system API.
+#[derive(Debug, Clone, Deserialize)]
+pub struct DirOperationOptions {
+    /// Whether the API should recursively perform the operation on the directory.
+    #[serde(default)]
+    pub recursive: bool,
+    /// The base directory of the operation.
+    /// The directory path of the BaseDirectory will be the prefix of the defined directory path.
+    pub dir: Option<BaseDirectory>,
+}
+
+/// The options for the file functions on the file system API.
+#[derive(Debug, Clone, Deserialize)]
+pub struct FileOperationOptions {
+    /// The base directory of the operation.
+    /// The directory path of the BaseDirectory will be the prefix of the defined file path.
+    pub dir: Option<BaseDirectory>,
+}
+
+fn resolve_path<R: Runtime>(
+    window: &Window<R>,
+    path: SafePathBuf,
+    dir: Option<BaseDirectory>,
+) -> Result<PathBuf> {
+    let path = if let Some(dir) = dir {
+        window
+            .path()
+            .resolve(&path, dir)
+            .map_err(Error::CannotResolvePath)?
+    } else {
+        path.as_ref().to_path_buf()
+    };
+    if window.fs_scope().is_allowed(&path) {
+        Ok(path)
+    } else {
+        Err(Error::PathForbidden(path))
+    }
+}
+
+#[tauri::command]
+pub fn read_file<R: Runtime>(
+    window: Window<R>,
+    path: SafePathBuf,
+    options: Option<FileOperationOptions>,
+) -> CommandResult<Vec<u8>> {
+    let resolved_path = resolve_path(&window, path, options.and_then(|o| o.dir))?;
+    fs::read(&resolved_path)
+        .with_context(|| format!("path: {}", resolved_path.display()))
+        .map_err(Into::into)
+}
+
+#[tauri::command]
+pub fn read_text_file<R: Runtime>(
+    window: Window<R>,
+    path: SafePathBuf,
+    options: Option<FileOperationOptions>,
+) -> CommandResult<String> {
+    let resolved_path = resolve_path(&window, path, options.and_then(|o| o.dir))?;
+    fs::read_to_string(&resolved_path)
+        .with_context(|| format!("path: {}", resolved_path.display()))
+        .map_err(Into::into)
+}
+
+#[tauri::command]
+pub fn write_file<R: Runtime>(
+    window: Window<R>,
+    path: SafePathBuf,
+    contents: Vec<u8>,
+    options: Option<FileOperationOptions>,
+) -> CommandResult<()> {
+    let resolved_path = resolve_path(&window, path, options.and_then(|o| o.dir))?;
+    File::create(&resolved_path)
+        .with_context(|| format!("path: {}", resolved_path.display()))
+        .map_err(Into::into)
+        .and_then(|mut f| {
+            f.write_all(&contents)
+                .map_err(|err| anyhow::anyhow!("{}", err))
+                .map_err(Into::into)
+        })
+}
+
+#[derive(Clone, Copy)]
+struct ReadDirOptions<'a> {
+    pub scope: Option<&'a FsScope>,
+}
+
+#[derive(Debug, Serialize)]
+#[non_exhaustive]
+pub struct DiskEntry {
+    /// The path to the entry.
+    pub path: PathBuf,
+    /// The name of the entry (file name with extension or directory name).
+    pub name: Option<String>,
+    /// The children of this entry if it's a directory.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub children: Option<Vec<DiskEntry>>,
+}
+
+fn read_dir_with_options<P: AsRef<Path>>(
+    path: P,
+    recursive: bool,
+    options: ReadDirOptions<'_>,
+) -> Result<Vec<DiskEntry>> {
+    let mut files_and_dirs: Vec<DiskEntry> = vec![];
+    for entry in fs::read_dir(path)? {
+        let path = entry?.path();
+        let path_as_string = path.display().to_string();
+
+        if let Ok(flag) = path.metadata().map(|m| m.is_dir()) {
+            let is_symlink = symlink_metadata(&path).map(|md| md.is_symlink())?;
+            files_and_dirs.push(DiskEntry {
+                path: path.clone(),
+                children: if flag {
+                    Some(
+                        if recursive
+                            && (!is_symlink
+                                || options.scope.map(|s| s.is_allowed(&path)).unwrap_or(true))
+                        {
+                            read_dir_with_options(&path_as_string, true, options)?
+                        } else {
+                            vec![]
+                        },
+                    )
+                } else {
+                    None
+                },
+                name: path
+                    .file_name()
+                    .map(|name| name.to_string_lossy())
+                    .map(|name| name.to_string()),
+            });
+        }
+    }
+    Result::Ok(files_and_dirs)
+}
+
+#[tauri::command]
+pub fn read_dir<R: Runtime>(
+    window: Window<R>,
+    path: SafePathBuf,
+    options: Option<DirOperationOptions>,
+) -> CommandResult<Vec<DiskEntry>> {
+    let (recursive, dir) = if let Some(options_value) = options {
+        (options_value.recursive, options_value.dir)
+    } else {
+        (false, None)
+    };
+    let resolved_path = resolve_path(&window, path, dir)?;
+    read_dir_with_options(
+        &resolved_path,
+        recursive,
+        ReadDirOptions {
+            scope: Some(&window.fs_scope()),
+        },
+    )
+    .with_context(|| format!("path: {}", resolved_path.display()))
+    .map_err(Into::into)
+}
+
+#[tauri::command]
+pub fn copy_file<R: Runtime>(
+    window: Window<R>,
+    source: SafePathBuf,
+    destination: SafePathBuf,
+    options: Option<FileOperationOptions>,
+) -> CommandResult<()> {
+    match options.and_then(|o| o.dir) {
+        Some(dir) => {
+            let src = resolve_path(&window, source, Some(dir))?;
+            let dest = resolve_path(&window, destination, Some(dir))?;
+            fs::copy(&src, &dest)
+                .with_context(|| format!("source: {}, dest: {}", src.display(), dest.display()))?
+        }
+        None => fs::copy(&source, &destination).with_context(|| {
+            format!(
+                "source: {}, dest: {}",
+                source.display(),
+                destination.display()
+            )
+        })?,
+    };
+    Ok(())
+}
+
+#[tauri::command]
+pub fn create_dir<R: Runtime>(
+    window: Window<R>,
+    path: SafePathBuf,
+    options: Option<DirOperationOptions>,
+) -> CommandResult<()> {
+    let (recursive, dir) = if let Some(options_value) = options {
+        (options_value.recursive, options_value.dir)
+    } else {
+        (false, None)
+    };
+    let resolved_path = resolve_path(&window, path, dir)?;
+    if recursive {
+        fs::create_dir_all(&resolved_path)
+            .with_context(|| format!("path: {}", resolved_path.display()))?;
+    } else {
+        fs::create_dir(&resolved_path)
+            .with_context(|| format!("path: {} (non recursive)", resolved_path.display()))?;
+    }
+
+    Ok(())
+}
+
+#[tauri::command]
+pub fn remove_dir<R: Runtime>(
+    window: Window<R>,
+    path: SafePathBuf,
+    options: Option<DirOperationOptions>,
+) -> CommandResult<()> {
+    let (recursive, dir) = if let Some(options_value) = options {
+        (options_value.recursive, options_value.dir)
+    } else {
+        (false, None)
+    };
+    let resolved_path = resolve_path(&window, path, dir)?;
+    if recursive {
+        fs::remove_dir_all(&resolved_path)
+            .with_context(|| format!("path: {}", resolved_path.display()))?;
+    } else {
+        fs::remove_dir(&resolved_path)
+            .with_context(|| format!("path: {} (non recursive)", resolved_path.display()))?;
+    }
+
+    Ok(())
+}
+
+#[tauri::command]
+pub fn remove_file<R: Runtime>(
+    window: Window<R>,
+    path: SafePathBuf,
+    options: Option<FileOperationOptions>,
+) -> CommandResult<()> {
+    let resolved_path = resolve_path(&window, path, options.and_then(|o| o.dir))?;
+    fs::remove_file(&resolved_path)
+        .with_context(|| format!("path: {}", resolved_path.display()))?;
+    Ok(())
+}
+
+#[tauri::command]
+pub fn rename_file<R: Runtime>(
+    window: Window<R>,
+    old_path: SafePathBuf,
+    new_path: SafePathBuf,
+    options: Option<FileOperationOptions>,
+) -> CommandResult<()> {
+    match options.and_then(|o| o.dir) {
+        Some(dir) => {
+            let old = resolve_path(&window, old_path, Some(dir))?;
+            let new = resolve_path(&window, new_path, Some(dir))?;
+            fs::rename(&old, &new)
+                .with_context(|| format!("old: {}, new: {}", old.display(), new.display()))?
+        }
+        None => fs::rename(&old_path, &new_path)
+            .with_context(|| format!("old: {}, new: {}", old_path.display(), new_path.display()))?,
+    }
+    Ok(())
+}
+
+#[tauri::command]
+pub fn exists<R: Runtime>(
+    window: Window<R>,
+    path: SafePathBuf,
+    options: Option<FileOperationOptions>,
+) -> CommandResult<bool> {
+    let resolved_path = resolve_path(&window, path, options.and_then(|o| o.dir))?;
+    Ok(resolved_path.exists())
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Permissions {
+    readonly: bool,
+    #[cfg(unix)]
+    mode: u32,
+}
+
+#[cfg(unix)]
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UnixMetadata {
+    dev: u64,
+    ino: u64,
+    mode: u32,
+    nlink: u64,
+    uid: u32,
+    gid: u32,
+    rdev: u64,
+    blksize: u64,
+    blocks: u64,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Metadata {
+    accessed_at_ms: u64,
+    created_at_ms: u64,
+    modified_at_ms: u64,
+    is_dir: bool,
+    is_file: bool,
+    is_symlink: bool,
+    size: u64,
+    permissions: Permissions,
+    #[cfg(unix)]
+    #[serde(flatten)]
+    unix: UnixMetadata,
+    #[cfg(windows)]
+    file_attributes: u32,
+}
+
+fn system_time_to_ms(time: std::io::Result<SystemTime>) -> u64 {
+    time.map(|t| {
+        let duration_since_epoch = t.duration_since(UNIX_EPOCH).unwrap();
+        duration_since_epoch.as_millis() as u64
+    })
+    .unwrap_or_default()
+}
+
+#[tauri::command]
+pub async fn metadata(path: PathBuf) -> Result<Metadata> {
+    let metadata = std::fs::metadata(path)?;
+    let file_type = metadata.file_type();
+    let permissions = metadata.permissions();
+    Ok(Metadata {
+        accessed_at_ms: system_time_to_ms(metadata.accessed()),
+        created_at_ms: system_time_to_ms(metadata.created()),
+        modified_at_ms: system_time_to_ms(metadata.modified()),
+        is_dir: file_type.is_dir(),
+        is_file: file_type.is_file(),
+        is_symlink: file_type.is_symlink(),
+        size: metadata.len(),
+        permissions: Permissions {
+            readonly: permissions.readonly(),
+            #[cfg(unix)]
+            mode: permissions.mode(),
+        },
+        #[cfg(unix)]
+        unix: UnixMetadata {
+            dev: metadata.dev(),
+            ino: metadata.ino(),
+            mode: metadata.mode(),
+            nlink: metadata.nlink(),
+            uid: metadata.uid(),
+            gid: metadata.gid(),
+            rdev: metadata.rdev(),
+            blksize: metadata.blksize(),
+            blocks: metadata.blocks(),
+        },
+        #[cfg(windows)]
+        file_attributes: metadata.file_attributes(),
+    })
+}

plugins/fs/src/error.rs

@@ -0,0 +1,22 @@
+use std::path::PathBuf;
+
+use serde::{Serialize, Serializer};
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+    #[error("forbidden path: {0}")]
+    PathForbidden(PathBuf),
+    #[error("failed to resolve path: {0}")]
+    CannotResolvePath(tauri::path::Error),
+}
+
+impl Serialize for Error {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_str(self.to_string().as_ref())
+    }
+}

plugins/fs/src/lib.rs

@@ -0,0 +1,33 @@
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+use tauri::{
+    plugin::{Builder as PluginBuilder, TauriPlugin},
+    Runtime,
+};
+
+mod commands;
+mod error;
+
+use error::Error;
+
+type Result<T> = std::result::Result<T, Error>;
+
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    PluginBuilder::new("fs")
+        .invoke_handler(tauri::generate_handler![
+            commands::read_file,
+            commands::read_text_file,
+            commands::write_file,
+            commands::read_dir,
+            commands::copy_file,
+            commands::create_dir,
+            commands::remove_dir,
+            commands::remove_file,
+            commands::rename_file,
+            commands::exists,
+            commands::metadata
+        ])
+        .build()
+}

pnpm-lock.yaml

@@ -77,7 +77,7 @@ importers:
         specifier: ^2.4.1
         version: 2.4.1
 
-  plugins/fs-extra:
+  plugins/fs:
     dependencies:
       '@tauri-apps/api':
         specifier: ^1.2.0
@@ -744,8 +744,8 @@ packages:
     resolution: {integrity: sha512-dRLjCWHYg4oaA77cxO64oO+7JwCwnIzkZPdrrC71jQmQtlhM556pwKo5bUzqvZndkVbeFLIIi+9TC40JNF5hNQ==}
     dev: true
 
-  /@types/node@18.11.18:
-    resolution: {integrity: sha512-DHQpWGjyQKSHj3ebjFI/wRKcqQcdR+MoFBygntYOZytCqNfkd2ZC4ARDJ2DQqhjH5p85Nnd3jhUJIXrszFX/JA==}
+  /@types/node@18.15.11:
+    resolution: {integrity: sha512-E5Kwq2n4SbMzQOn6wnmBjuK9ouqlURrcZDVfbo9ftDDTFt3nk7ZKK4GMOzoYgnpQJKcxwQw+lGaBvvlMo0qN/Q==}
     dev: true
 
   /@types/pug@2.0.6:
@@ -759,7 +759,7 @@ packages:
   /@types/sass@1.43.1:
     resolution: {integrity: sha512-BPdoIt1lfJ6B7rw35ncdwBZrAssjcwzI5LByIrYs+tpXlj/CAkuVdRsgZDdP4lq5EjyWzwxZCqAoFyHKFwp32g==}
     dependencies:
-      '@types/node': 18.11.18
+      '@types/node': 18.15.11
     dev: true
 
   /@types/semver@7.3.13: