tauri-plugin-fs-stream 0.4.0

File Streaming API for Tauri
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

Note: **I’m using a translation tool, so there may be some inappropriate expressions.**

# Overview

This plugin provides functions that create `ReadableStream` and  `WritableStream` from a file path.

# Setup
First, install this plugin to your Tauri project:

`src-tauri/Cargo.toml`

```toml
[dependencies]
tauri-plugin-fs-stream = "=0.4.0"
```

Next, register this plugin in your Tauri project:

`src-tauri/src/lib.rs`

```rust
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_fs_stream::init()) // This
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

Then, set the APIs and file paths that can be used from the Javascript:

`src-tauri/capabilities/*.json`
```json
{
    "permissions": [
        {
            "identifier": "fs-stream:allow-open-read-file-stream",
            "allow": ["$APPDATA/my-data/**/*"]
        },
        {
            "identifier": "fs-stream:allow-open-read-text-file-lines-stream",
            "allow": ["$APPDATA/my-data/**/*"]
        },
        {
            "identifier": "fs-stream:allow-open-write-file-stream",
            "allow": ["$APPDATA/my-data/**/*"],
            "deny": ["$APPDATA/my-data/readonly/**/*"]
        }
    ]
}
```

Finally, install the JavaScript Guest bindings using whichever JavaScript package manager you prefer:

```bash
pnpm add tauri-plugin-fs-stream-api@0.4.0 -E
# or
npm install tauri-plugin-fs-stream-api@0.4.0 --save-exact
# or
yarn add tauri-plugin-fs-stream-api@0.4.0 --exact
```

**NOTE**: Please make sure that the Rust-side [`tauri-plugin-fs-stream`](https://crates.io/crates/tauri-plugin-fs-stream) and the JavaScript-side [`tauri-plugin-fs-stream-api`](https://www.npmjs.com/package/tauri-plugin-fs-stream-api?activeTab=readme) versions match exactly.

# Example
```typescript
import { openReadFileStream, openWriteFileStream } from "tauri-plugin-fs-stream-api";

async function convertFile(
  inputPath: string,
  outputPath: string,
  convertor: TransformStream<Uint8Array<ArrayBuffer>, Uint8Array>
) {

  let input: ReadableStream<Uint8Array<ArrayBuffer>> | null = null
  let output: WritableStream<Uint8Array> | null = null
  try {
    input = await openReadFileStream(inputPath)
    output = await openWriteFileStream(outputPath)
    await input.pipeThrough(convertor).pipeTo(output)
  }
  catch (e) {
    await input?.cancel().catch(() => {})
    await output?.abort().catch(() => {})
    throw e
  }
}
```

# File Access
Access control for file paths follows [the same model as the fs plugin](https://v2.tauri.app/reference/javascript/fs/#security).

This plugin prevents path traversal and can access only the paths explicitly declared in the capability file. In that case, you can also configure `plugins.fs-stream.requireLiteralLeadingDot` in `src-tauri/tauri.conf.json` like with the fs plugin.

An exception applies to files that the user explicitly selects through drag and drop or via  [the dialog plugin](https://v2.tauri.app/plugin/dialog/). Such files are accessible even if they are not declared in the capability configuration. And these permissions can be persisted using [the persisted scope plugin](https://v2.tauri.app/plugin/persisted-scope/), allowing access to remain available across application restarts. Note that to use these features, the fs plugin must be registered in your Tauri project. In other words, `tauri_plugin_fs::init()` must be in `src-tauri/src/lib.rs`.

# License
This project is licensed under either of

 * MIT license
 * Apache License (Version 2.0)

at your option.