tauri-apps/tauri
1
1
Fork 0
mirror of https://github.com/tauri-apps/tauri.git synced 2024-09-17 11:17:28 +03:00
Code Issues Packages Projects Releases Wiki Activity

refactor(core): move file system endpoints to its own plugin (#6716)

Browse Source
This commit is contained in:
Lucas Fernandes Nogueira 2023-04-16 05:20:58 -07:00 committed by GitHub
parent 22a7633816
commit fc4d687ef0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
19 changed files with 91 additions and 1253 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.changes/move-fs.md Normal file
View File

@ -0,0 +1,6 @@
---
"api": patch
"tauri": patch
---
Moved the file system APIs to its own plugin in the plugins-workspace repository.

10
core/tauri/scripts/bundle.global.js
View File

File diff suppressed because one or more lines are too long

1
core/tauri/scripts/bundle.js
View File

File diff suppressed because one or more lines are too long

11
core/tauri/src/endpoints.rs
View File

@ -18,8 +18,6 @@ mod clipboard;
#[cfg(dialog_any)]
mod dialog;
mod event;
#[cfg(fs_any)]
mod file_system;
#[cfg(global_shortcut_any)]
mod global_shortcut;
#[cfg(http_any)]
@ -70,8 +68,6 @@ enum Module {
App(app::Cmd),
#[cfg(process_any)]
Process(process::Cmd),
#[cfg(fs_any)]
Fs(file_system::Cmd),
#[cfg(os_any)]
Os(operating_system::Cmd),
Window(Box<window::Cmd>),
@ -116,13 +112,6 @@ impl Module {
.and_then(|r| r.json)
.map_err(InvokeError::from_anyhow)
}),
#[cfg(fs_any)]
Self::Fs(cmd) => resolver.respond_async(async move {
cmd
.run(context)
.and_then(|r| r.json)
.map_err(InvokeError::from_anyhow)
}),
#[cfg(os_any)]
Self::Os(cmd) => resolver.respond_async(async move {
cmd

432
core/tauri/src/endpoints/file_system.rs
View File

@ -1,432 +0,0 @@
// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT
#![allow(unused_imports)]
use crate::{
api::{dir, file},
path::{BaseDirectory, SafePathBuf},
scope::Scopes,
Config, Env, Manager, PackageInfo, Runtime, Window,
};
use super::InvokeContext;
#[allow(unused_imports)]
use anyhow::Context;
use serde::{
de::{Deserializer, Error as DeError},
Deserialize, Serialize,
};
use tauri_macros::{command_enum, module_command_handler, CommandModule};
use std::fmt::{Debug, Formatter};
use std::{
fs,
fs::File,
io::Write,
path::{Component, Path},
sync::Arc,
};
/// 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>,
}
/// The API descriptor.
#[command_enum]
#[derive(Deserialize, CommandModule)]
#[serde(tag = "cmd", rename_all = "camelCase")]
pub(crate) enum Cmd {
/// The read binary file API.
#[cmd(fs_read_file, "fs > readFile")]
ReadFile {
path: SafePathBuf,
options: Option<FileOperationOptions>,
},
/// The read binary file API.
#[cmd(fs_read_file, "fs > readFile")]
ReadTextFile {
path: SafePathBuf,
options: Option<FileOperationOptions>,
},
/// The write file API.
#[cmd(fs_write_file, "fs > writeFile")]
WriteFile {
path: SafePathBuf,
contents: Vec<u8>,
options: Option<FileOperationOptions>,
},
/// The read dir API.
#[cmd(fs_read_dir, "fs > readDir")]
ReadDir {
path: SafePathBuf,
options: Option<DirOperationOptions>,
},
/// The copy file API.
#[cmd(fs_copy_file, "fs > copyFile")]
CopyFile {
source: SafePathBuf,
destination: SafePathBuf,
options: Option<FileOperationOptions>,
},
/// The create dir API.
#[cmd(fs_create_dir, "fs > createDir")]
CreateDir {
path: SafePathBuf,
options: Option<DirOperationOptions>,
},
/// The remove dir API.
#[cmd(fs_remove_dir, "fs > removeDir")]
RemoveDir {
path: SafePathBuf,
options: Option<DirOperationOptions>,
},
/// The remove file API.
#[cmd(fs_remove_file, "fs > removeFile")]
RemoveFile {
path: SafePathBuf,
options: Option<FileOperationOptions>,
},
/// The rename file API.
#[cmd(fs_rename_file, "fs > renameFile")]
#[serde(rename_all = "camelCase")]
RenameFile {
old_path: SafePathBuf,
new_path: SafePathBuf,
options: Option<FileOperationOptions>,
},
/// The exists API.
#[cmd(fs_exists, "fs > exists")]
Exists {
path: SafePathBuf,
options: Option<FileOperationOptions>,
},
}
impl Cmd {
#[module_command_handler(fs_read_file)]
fn read_file<R: Runtime>(
context: InvokeContext<R>,
path: SafePathBuf,
options: Option<FileOperationOptions>,
) -> super::Result<Vec<u8>> {
let resolved_path = resolve_path(&context.window, path, options.and_then(|o| o.dir))?;
file::read_binary(&resolved_path)
.with_context(|| format!("path: {}", resolved_path.display()))
.map_err(Into::into)
}
#[module_command_handler(fs_read_file)]
fn read_text_file<R: Runtime>(
context: InvokeContext<R>,
path: SafePathBuf,
options: Option<FileOperationOptions>,
) -> super::Result<String> {
let resolved_path = resolve_path(&context.window, path, options.and_then(|o| o.dir))?;
file::read_string(&resolved_path)
.with_context(|| format!("path: {}", resolved_path.display()))
.map_err(Into::into)
}
#[module_command_handler(fs_write_file)]
fn write_file<R: Runtime>(
context: InvokeContext<R>,
path: SafePathBuf,
contents: Vec<u8>,
options: Option<FileOperationOptions>,
) -> super::Result<()> {
let resolved_path = resolve_path(&context.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| err.into()))
}
#[module_command_handler(fs_read_dir)]
fn read_dir<R: Runtime>(
context: InvokeContext<R>,
path: SafePathBuf,
options: Option<DirOperationOptions>,
) -> super::Result<Vec<dir::DiskEntry>> {
let (recursive, dir) = if let Some(options_value) = options {
(options_value.recursive, options_value.dir)
} else {
(false, None)
};
let resolved_path = resolve_path(&context.window, path, dir)?;
dir::read_dir_with_options(
&resolved_path,
recursive,
dir::ReadDirOptions {
scope: Some(&context.window.state::<Scopes>().fs),
},
)
.with_context(|| format!("path: {}", resolved_path.display()))
.map_err(Into::into)
}
#[module_command_handler(fs_copy_file)]
fn copy_file<R: Runtime>(
context: InvokeContext<R>,
source: SafePathBuf,
destination: SafePathBuf,
options: Option<FileOperationOptions>,
) -> super::Result<()> {
let (src, dest) = match options.and_then(|o| o.dir) {
Some(dir) => (
resolve_path(&context.window, source, Some(dir))?,
resolve_path(&context.window, destination, Some(dir))?,
),
None => (source, destination),
};
fs::copy(src.clone(), dest.clone())
.with_context(|| format!("source: {}, dest: {}", src.display(), dest.display()))?;
Ok(())
}
#[module_command_handler(fs_create_dir)]
fn create_dir<R: Runtime>(
context: InvokeContext<R>,
path: SafePathBuf,
options: Option<DirOperationOptions>,
) -> super::Result<()> {
let (recursive, dir) = if let Some(options_value) = options {
(options_value.recursive, options_value.dir)
} else {
(false, None)
};
let resolved_path = resolve_path(&context.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(())
}
#[module_command_handler(fs_remove_dir)]
fn remove_dir<R: Runtime>(
context: InvokeContext<R>,
path: SafePathBuf,
options: Option<DirOperationOptions>,
) -> super::Result<()> {
let (recursive, dir) = if let Some(options_value) = options {
(options_value.recursive, options_value.dir)
} else {
(false, None)
};
let resolved_path = resolve_path(&context.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(())
}
#[module_command_handler(fs_remove_file)]
fn remove_file<R: Runtime>(
context: InvokeContext<R>,
path: SafePathBuf,
options: Option<FileOperationOptions>,
) -> super::Result<()> {
let resolved_path = resolve_path(&context.window, path, options.and_then(|o| o.dir))?;
fs::remove_file(&resolved_path)
.with_context(|| format!("path: {}", resolved_path.display()))?;
Ok(())
}
#[module_command_handler(fs_rename_file)]
fn rename_file<R: Runtime>(
context: InvokeContext<R>,
old_path: SafePathBuf,
new_path: SafePathBuf,
options: Option<FileOperationOptions>,
) -> super::Result<()> {
let (old, new) = match options.and_then(|o| o.dir) {
Some(dir) => (
resolve_path(&context.window, old_path, Some(dir))?,
resolve_path(&context.window, new_path, Some(dir))?,
),
None => (old_path, new_path),
};
fs::rename(&old, &new)
.with_context(|| format!("old: {}, new: {}", old.display(), new.display()))
.map_err(Into::into)
}
#[module_command_handler(fs_exists)]
fn exists<R: Runtime>(
context: InvokeContext<R>,
path: SafePathBuf,
options: Option<FileOperationOptions>,
) -> super::Result<bool> {
let resolved_path = resolve_path(&context.window, path, options.and_then(|o| o.dir))?;
Ok(resolved_path.as_ref().exists())
}
}
#[allow(dead_code)]
fn resolve_path<R: Runtime>(
window: &Window<R>,
path: SafePathBuf,
dir: Option<BaseDirectory>,
) -> super::Result<SafePathBuf> {
match if let Some(dir) = dir {
window.path().resolve(&path, dir)
} else {
Ok(path.as_ref().to_path_buf())
} {
Ok(path) => {
if window.state::<Scopes>().fs.is_allowed(&path) {
Ok(
// safety: the path is resolved by Tauri so it is safe
unsafe { SafePathBuf::new_unchecked(path) },
)
} else {
Err(anyhow::anyhow!(
crate::Error::PathNotAllowed(path).to_string()
))
}
}
Err(e) => super::Result::<SafePathBuf>::Err(e.into())
.with_context(|| format!("path: {}, base dir: {dir:?}", path.display())),
}
}
#[cfg(test)]
mod tests {
use super::{BaseDirectory, DirOperationOptions, FileOperationOptions, SafePathBuf};
use quickcheck::{Arbitrary, Gen};
impl Arbitrary for BaseDirectory {
fn arbitrary(g: &mut Gen) -> Self {
if bool::arbitrary(g) {
BaseDirectory::AppData
} else {
BaseDirectory::Resource
}
}
}
impl Arbitrary for FileOperationOptions {
fn arbitrary(g: &mut Gen) -> Self {
Self {
dir: Option::arbitrary(g),
}
}
}
impl Arbitrary for DirOperationOptions {
fn arbitrary(g: &mut Gen) -> Self {
Self {
recursive: bool::arbitrary(g),
dir: Option::arbitrary(g),
}
}
}
#[tauri_macros::module_command_test(fs_read_file, "fs > readFile")]
#[quickcheck_macros::quickcheck]
fn read_file(path: SafePathBuf, options: Option<FileOperationOptions>) {
let res = super::Cmd::read_file(crate::test::mock_invoke_context(), path, options);
crate::test_utils::assert_not_allowlist_error(res);
}
#[tauri_macros::module_command_test(fs_write_file, "fs > writeFile")]
#[quickcheck_macros::quickcheck]
fn write_file(path: SafePathBuf, contents: Vec<u8>, options: Option<FileOperationOptions>) {
let res = super::Cmd::write_file(crate::test::mock_invoke_context(), path, contents, options);
crate::test_utils::assert_not_allowlist_error(res);
}
#[tauri_macros::module_command_test(fs_read_dir, "fs > readDir")]
#[quickcheck_macros::quickcheck]
fn read_dir(path: SafePathBuf, options: Option<DirOperationOptions>) {
let res = super::Cmd::read_dir(crate::test::mock_invoke_context(), path, options);
crate::test_utils::assert_not_allowlist_error(res);
}
#[tauri_macros::module_command_test(fs_copy_file, "fs > copyFile")]
#[quickcheck_macros::quickcheck]
fn copy_file(
source: SafePathBuf,
destination: SafePathBuf,
options: Option<FileOperationOptions>,
) {
let res = super::Cmd::copy_file(
crate::test::mock_invoke_context(),
source,
destination,
options,
);
crate::test_utils::assert_not_allowlist_error(res);
}
#[tauri_macros::module_command_test(fs_create_dir, "fs > createDir")]
#[quickcheck_macros::quickcheck]
fn create_dir(path: SafePathBuf, options: Option<DirOperationOptions>) {
let res = super::Cmd::create_dir(crate::test::mock_invoke_context(), path, options);
crate::test_utils::assert_not_allowlist_error(res);
}
#[tauri_macros::module_command_test(fs_remove_dir, "fs > removeDir")]
#[quickcheck_macros::quickcheck]
fn remove_dir(path: SafePathBuf, options: Option<DirOperationOptions>) {
let res = super::Cmd::remove_dir(crate::test::mock_invoke_context(), path, options);
crate::test_utils::assert_not_allowlist_error(res);
}
#[tauri_macros::module_command_test(fs_remove_file, "fs > removeFile")]
#[quickcheck_macros::quickcheck]
fn remove_file(path: SafePathBuf, options: Option<FileOperationOptions>) {
let res = super::Cmd::remove_file(crate::test::mock_invoke_context(), path, options);
crate::test_utils::assert_not_allowlist_error(res);
}
#[tauri_macros::module_command_test(fs_rename_file, "fs > renameFile")]
#[quickcheck_macros::quickcheck]
fn rename_file(
old_path: SafePathBuf,
new_path: SafePathBuf,
options: Option<FileOperationOptions>,
) {
let res = super::Cmd::rename_file(
crate::test::mock_invoke_context(),
old_path,
new_path,
options,
);
crate::test_utils::assert_not_allowlist_error(res);
}
#[tauri_macros::module_command_test(fs_exists, "fs > exists")]
#[quickcheck_macros::quickcheck]
fn exists(path: SafePathBuf, options: Option<FileOperationOptions>) {
let res = super::Cmd::exists(crate::test::mock_invoke_context(), path, options);
crate::test_utils::assert_not_allowlist_error(res);
}
}

5
core/tauri/src/path/mod.rs
View File

@ -44,11 +44,6 @@ impl SafePathBuf {
}
}
#[allow(dead_code)]
pub(crate) unsafe fn new_unchecked(path: PathBuf) -> Self {
Self(path)
}
/// Returns an object that implements [`std::fmt::Display`] for safely printing paths.
///
/// See [`PathBuf#method.display`] for more information.

2
examples/api/dist/assets/index.css vendored
View File

File diff suppressed because one or more lines are too long

83
examples/api/dist/assets/index.js vendored
View File

File diff suppressed because one or more lines are too long

4
examples/api/src-tauri/Cargo.toml
View File

@ -25,6 +25,10 @@ tauri-plugin-cli = { git = "https://github.com/tauri-apps/plugins-workspace", br
tauri = { path = "../../../core/tauri" }
tauri-build = { path = "../../../core/tauri-build" }
[patch.'https://github.com/tauri-apps/tauri']
tauri = { path = "../../../core/tauri" }
tauri-build = { path = "../../../core/tauri-build" }
[dependencies.tauri]
path = "../../../core/tauri"
features = [

1
examples/api/src-tauri/tauri.conf.json
View File

@ -35,7 +35,6 @@
{
"short": "v",
"name": "verbose",
"multipleOccurrences": true,
"description": "Verbosity level"
}
],

6
examples/api/src/App.svelte
View File

@ -8,7 +8,6 @@
import Cli from './views/Cli.svelte'
import Communication from './views/Communication.svelte'
import Dialog from './views/Dialog.svelte'
import FileSystem from './views/FileSystem.svelte'
import Http from './views/Http.svelte'
import Notifications from './views/Notifications.svelte'
import Window from './views/Window.svelte'
@ -61,11 +60,6 @@
component: Dialog,
icon: 'i-codicon-multiple-windows'
},
{
label: 'File system',
component: FileSystem,
icon: 'i-codicon-files'
},
{
label: 'HTTP',
component: Http,

33
examples/api/src/views/Dialog.svelte
View File

@ -1,9 +1,7 @@
<script>
import { open, save } from '@tauri-apps/api/dialog'
import { readBinaryFile } from '@tauri-apps/api/fs'
export let onMessage
export let insecureRenderHtml
let defaultPath = null
let filter = null
let multiple = false
@ -36,36 +34,7 @@
multiple,
directory
})
.then(function (res) {
if (Array.isArray(res)) {
onMessage(res)
} else {
var pathToRead = res
var isFile = pathToRead.match(/\S+\.\S+$/g)
readBinaryFile(pathToRead)
.then(function (response) {
if (isFile) {
if (
pathToRead.includes('.png') ||
pathToRead.includes('.jpg')
) {
arrayBufferToBase64(
new Uint8Array(response),
function (base64) {
var src = 'data:image/png;base64,' + base64
insecureRenderHtml('<img src="' + src + '"></img>')
}
)
} else {
onMessage(res)
}
} else {
onMessage(res)
}
})
.catch(onMessage(res))
}
})
.then(onMessage)
.catch(onMessage)
}

106
examples/api/src/views/FileSystem.svelte
View File

@ -1,106 +0,0 @@
<script>
import {
readBinaryFile,
writeTextFile,
readDir,
Dir
} from '@tauri-apps/api/fs'
import { convertFileSrc } from '@tauri-apps/api/tauri'
export let onMessage
export let insecureRenderHtml
let pathToRead = ''
let img
function getDir() {
const dirSelect = document.getElementById('dir')
return dirSelect.value ? parseInt(dir.value) : null
}
function arrayBufferToBase64(buffer, callback) {
const blob = new Blob([buffer], {
type: 'application/octet-binary'
})
const reader = new FileReader()
reader.onload = function (evt) {
const dataurl = evt.target.result
callback(dataurl.substr(dataurl.indexOf(',') + 1))
}
reader.readAsDataURL(blob)
}
const DirOptions = Object.keys(Dir)
.filter((key) => isNaN(parseInt(key)))
.map((dir) => [dir, Dir[dir]])
function read() {
const isFile = pathToRead.match(/\S+\.\S+$/g)
const opts = {
dir: getDir()
}
const promise = isFile
? readBinaryFile(pathToRead, opts)
: readDir(pathToRead, opts)
promise
.then(function (response) {
if (isFile) {
if (pathToRead.includes('.png') || pathToRead.includes('.jpg')) {
arrayBufferToBase64(new Uint8Array(response), function (base64) {
const src = 'data:image/png;base64,' + base64
insecureRenderHtml('<img src="' + src + '"></img>')
})
} else {
const value = String.fromCharCode.apply(null, response)
insecureRenderHtml(
'<textarea id="file-response"></textarea><button id="file-save">Save</button>'
)
setTimeout(() => {
const fileInput = document.getElementById('file-response')
fileInput.value = value
document
.getElementById('file-save')
.addEventListener('click', function () {
writeTextFile(pathToRead, fileInput.value, {
dir: getDir()
}).catch(onMessage)
})
})
}
} else {
onMessage(response)
}
})
.catch(onMessage)
}
function setSrc() {
img.src = convertFileSrc(pathToRead)
}
</script>
<form class="flex flex-col" on:submit|preventDefault={read}>
<div class="flex gap-1">
<select class="input" id="dir">
<option value="">None</option>
{#each DirOptions as dir}
<option value={dir[1]}>{dir[0]}</option>
{/each}
</select>
<input
class="input grow"
id="path-to-read"
placeholder="Type the path to read..."
bind:value={pathToRead}
/>
</div>
<br />
<div>
<button class="btn" id="read">Read</button>
<button class="btn" type="button" on:click={setSrc}>Use as img src</button>
</div>
</form>
<br />
<img alt="" bind:this={img} />

2
examples/api/yarn.lock
View File

@ -98,7 +98,7 @@
svelte-hmr "^0.14.12"
"@tauri-apps/api@../../tooling/api/dist":
version "1.0.2"
version "2.0.0-alpha.3"
"@unocss/cli@0.39.3":
version "0.39.3"

2
tooling/api/docs/js-api.json
View File

File diff suppressed because one or more lines are too long

605
tooling/api/src/fs.ts
View File

@ -1,605 +0,0 @@
// 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,
* "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 { invokeTauriCommand } from './helpers/tauri'
/**
* @since 1.0.0
*/
export 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 invokeTauriCommand<string>({
__tauriModule: 'Fs',
message: {
cmd: 'readTextFile',
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 invokeTauriCommand<number[]>({
__tauriModule: 'Fs',
message: {
cmd: 'readFile',
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 invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'writeFile',
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 invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'writeFile',
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 invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'readDir',
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 invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'createDir',
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 invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'removeDir',
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 invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'copyFile',
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 invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'removeFile',
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 invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'renameFile',
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.1.0
*/
async function exists(path: string, options: FsOptions = {}): Promise<boolean> {
return invokeTauriCommand({
__tauriModule: 'Fs',
message: {
cmd: 'exists',
path,
options
}
})
}
export type {
FsOptions,
FsDirOptions,
FsTextFileOption,
BinaryFileContents,
FsBinaryFileOption,
FileEntry
}
export {
BaseDirectory as Dir,
readTextFile,
readBinaryFile,
writeTextFile,
writeTextFile as writeFile,
writeBinaryFile,
readDir,
createDir,
removeDir,
copyFile,
removeFile,
renameFile,
exists
}

2
tooling/api/src/index.ts
View File

@ -17,7 +17,6 @@ import * as app from './app'
import * as clipboard from './clipboard'
import * as dialog from './dialog'
import * as event from './event'
import * as fs from './fs'
import * as globalShortcut from './globalShortcut'
import * as http from './http'
import * as notification from './notification'
@ -38,7 +37,6 @@ export {
clipboard,
dialog,
event,
fs,
globalShortcut,
http,
notification,

31
tooling/api/src/path.ts
View File

@ -24,9 +24,38 @@
*/
import { invoke } from './tauri'
import { BaseDirectory } from './fs'
import { isWindows } from './helpers/os-check'
/**
* @since 2.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
}
/**
* Returns the path to the suggested directory for your app's config files.
* Resolves to `${configDir}/${bundleIdentifier}`, where `bundleIdentifier` is the value [`tauri.bundle.identifier`](https://tauri.app/v1/api/config/#bundleconfig.identifier) is configured in `tauri.conf.json`.

2
tooling/cli/node/test/jest/fixtures/app/dist/index.html vendored
View File

@ -123,7 +123,7 @@
}
testFs(null).then(function () {
testFs(window.__TAURI__.fs.Dir.Config)
testFs(window.__TAURI__.path.BaseDirectory.Config)
})
setTimeout(function () {