feat(shell): add plugin (#327)
Lucas Fernandes Nogueira
2 years ago
committed by
GitHub
parent
89fb40caac
commit
8ed00adaa0
@ -0,0 +1,18 @@
|
||||
[package]
|
||||
name = "tauri-plugin-shell"
|
||||
version = "0.1.0"
|
||||
edition.workspace = true
|
||||
authors.workspace = true
|
||||
license.workspace = true
|
||||
|
||||
[dependencies]
|
||||
serde.workspace = true
|
||||
serde_json.workspace = true
|
||||
tauri.workspace = true
|
||||
log.workspace = true
|
||||
thiserror.workspace = true
|
||||
shared_child = "1"
|
||||
regex = "1"
|
||||
open = "4"
|
||||
encoding_rs = "0.8"
|
||||
os_pipe = "1"
|
||||
@ -0,0 +1,20 @@
|
||||
SPDXVersion: SPDX-2.1
|
||||
DataLicense: CC0-1.0
|
||||
PackageName: tauri
|
||||
DataFormat: SPDXRef-1
|
||||
PackageSupplier: Organization: The Tauri Programme in the Commons Conservancy
|
||||
PackageHomePage: https://tauri.app
|
||||
PackageLicenseDeclared: Apache-2.0
|
||||
PackageLicenseDeclared: MIT
|
||||
PackageCopyrightText: 2019-2022, The Tauri Programme in the Commons Conservancy
|
||||
PackageSummary: <text>Tauri is a rust project that enables developers to make secure
|
||||
and small desktop applications using a web frontend.
|
||||
</text>
|
||||
PackageComment: <text>The package includes the following libraries; see
|
||||
Relationship information.
|
||||
</text>
|
||||
Created: 2019-05-20T09:00:00Z
|
||||
PackageDownloadLocation: git://github.com/tauri-apps/tauri
|
||||
PackageDownloadLocation: git+https://github.com/tauri-apps/tauri.git
|
||||
PackageDownloadLocation: git+ssh://github.com/tauri-apps/tauri.git
|
||||
Creator: Person: Daniel Thompson-Yvetot
|
||||
@ -0,0 +1,177 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2017 - Present Tauri Apps Contributors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@ -0,0 +1,65 @@
|
||||
|
||||
|
||||
<!-- description -->
|
||||
|
||||
## Install
|
||||
|
||||
_This plugin requires a Rust version of at least **1.64**_
|
||||
|
||||
There are three general methods of installation that we can recommend.
|
||||
|
||||
1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked)
|
||||
2. Pull sources directly from Github using git tags / revision hashes (most secure)
|
||||
3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use)
|
||||
|
||||
Install the Core plugin by adding the following to your `Cargo.toml` file:
|
||||
|
||||
`src-tauri/Cargo.toml`
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
<!-- plugin here --> = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" }
|
||||
```
|
||||
|
||||
You can install the JavaScript Guest bindings using your preferred JavaScript package manager:
|
||||
|
||||
> 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 <!-- plugin here -->
|
||||
# or
|
||||
npm add <!-- plugin here -->
|
||||
# or
|
||||
yarn add <!-- plugin here -->
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
First you need to register the core plugin with Tauri:
|
||||
|
||||
`src-tauri/src/main.rs`
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.plugin(<!-- plugin here -->)
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
Afterwards all the plugin's APIs are available through the JavaScript guest bindings:
|
||||
|
||||
```javascript
|
||||
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
PRs accepted. Please make sure to read the Contributing Guide before making a pull request.
|
||||
|
||||
## License
|
||||
|
||||
Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy.
|
||||
|
||||
MIT or MIT/Apache 2.0 where applicable.
|
||||
@ -0,0 +1,657 @@
|
||||
// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
/**
|
||||
* Access the system shell.
|
||||
* Allows you to spawn child processes and manage files and URLs using their default application.
|
||||
*
|
||||
* The APIs must be added to [`tauri.allowlist.shell`](https://tauri.app/v1/api/config/#allowlistconfig.shell) in `tauri.conf.json`:
|
||||
* ```json
|
||||
* {
|
||||
* "tauri": {
|
||||
* "allowlist": {
|
||||
* "shell": {
|
||||
* "all": true, // enable all shell APIs
|
||||
* "execute": true, // enable process spawn APIs
|
||||
* "sidecar": true, // enable spawning sidecars
|
||||
* "open": true // enable opening files/URLs using the default program
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
* It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
*
|
||||
* ## Security
|
||||
*
|
||||
* This API has a scope configuration that forces you to restrict the programs and arguments that can be used.
|
||||
*
|
||||
* ### Restricting access to the {@link open | `open`} API
|
||||
*
|
||||
* On the allowlist, `open: true` means that the {@link open} API can be used with any URL,
|
||||
* as the argument is validated with the `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+` regex.
|
||||
* You can change that regex by changing the boolean value to a string, e.g. `open: ^https://github.com/`.
|
||||
*
|
||||
* ### Restricting access to the {@link Command | `Command`} APIs
|
||||
*
|
||||
* The `shell` allowlist object has a `scope` field that defines an array of CLIs that can be used.
|
||||
* Each CLI is a configuration object `{ name: string, cmd: string, sidecar?: bool, args?: boolean | Arg[] }`.
|
||||
*
|
||||
* - `name`: the unique identifier of the command, passed to the {@link Command.create | Command.create function}.
|
||||
* If it's a sidecar, this must be the value defined on `tauri.conf.json > tauri > bundle > externalBin`.
|
||||
* - `cmd`: the program that is executed on this configuration. If it's a sidecar, this value is ignored.
|
||||
* - `sidecar`: whether the object configures a sidecar or a system program.
|
||||
* - `args`: the arguments that can be passed to the program. By default no arguments are allowed.
|
||||
* - `true` means that any argument list is allowed.
|
||||
* - `false` means that no arguments are allowed.
|
||||
* - otherwise an array can be configured. Each item is either a string representing the fixed argument value
|
||||
* or a `{ validator: string }` that defines a regex validating the argument value.
|
||||
*
|
||||
* #### Example scope configuration
|
||||
*
|
||||
* CLI: `git commit -m "the commit message"`
|
||||
*
|
||||
* Configuration:
|
||||
* ```json
|
||||
* {
|
||||
* "scope": [
|
||||
* {
|
||||
* "name": "run-git-commit",
|
||||
* "cmd": "git",
|
||||
* "args": ["commit", "-m", { "validator": "\\S+" }]
|
||||
* }
|
||||
* ]
|
||||
* }
|
||||
* ```
|
||||
* Usage:
|
||||
* ```typescript
|
||||
* import { Command } from 'tauri-plugin-shell-api'
|
||||
* Command.create('run-git-commit', ['commit', '-m', 'the commit message'])
|
||||
* ```
|
||||
*
|
||||
* Trying to execute any API with a program not configured on the scope results in a promise rejection due to denied access.
|
||||
*
|
||||
* @module
|
||||
*/
|
||||
|
||||
import { invoke, transformCallback } from '@tauri-apps/api/tauri'
|
||||
|
||||
/**
|
||||
* @since 1.0.0
|
||||
*/
|
||||
interface SpawnOptions {
|
||||
/** Current working directory. */
|
||||
cwd?: string
|
||||
/** Environment variables. set to `null` to clear the process env. */
|
||||
env?: Record<string, string>
|
||||
/**
|
||||
* Character encoding for stdout/stderr
|
||||
*
|
||||
* @since 1.1.0
|
||||
* */
|
||||
encoding?: string
|
||||
}
|
||||
|
||||
/** @ignore */
|
||||
interface InternalSpawnOptions extends SpawnOptions {
|
||||
sidecar?: boolean
|
||||
}
|
||||
|
||||
/**
|
||||
* @since 1.0.0
|
||||
*/
|
||||
interface ChildProcess<O extends IOPayload> {
|
||||
/** Exit code of the process. `null` if the process was terminated by a signal on Unix. */
|
||||
code: number | null
|
||||
/** If the process was terminated by a signal, represents that signal. */
|
||||
signal: number | null
|
||||
/** The data that the process wrote to `stdout`. */
|
||||
stdout: O
|
||||
/** The data that the process wrote to `stderr`. */
|
||||
stderr: O
|
||||
}
|
||||
|
||||
/**
|
||||
* Spawns a process.
|
||||
*
|
||||
* @ignore
|
||||
* @param program The name of the scoped command.
|
||||
* @param onEvent Event handler.
|
||||
* @param args Program arguments.
|
||||
* @param options Configuration for the process spawn.
|
||||
* @returns A promise resolving to the process id.
|
||||
*/
|
||||
async function execute<O extends IOPayload>(
|
||||
onEvent: (event: CommandEvent<O>) => void,
|
||||
program: string,
|
||||
args: string | string[] = [],
|
||||
options?: InternalSpawnOptions
|
||||
): Promise<number> {
|
||||
if (typeof args === 'object') {
|
||||
Object.freeze(args)
|
||||
}
|
||||
|
||||
return invoke<number>('plugin:shell|execute', {
|
||||
program,
|
||||
args,
|
||||
options,
|
||||
onEventFn: transformCallback(onEvent)
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* @since 1.0.0
|
||||
*/
|
||||
class EventEmitter<E extends Record<string, any>> {
|
||||
/** @ignore */
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
|
||||
private eventListeners: Record<keyof E, Array<(arg: any) => void>> =
|
||||
Object.create(null)
|
||||
|
||||
/**
|
||||
* Alias for `emitter.on(eventName, listener)`.
|
||||
*
|
||||
* @since 1.1.0
|
||||
*/
|
||||
addListener<N extends keyof E>(
|
||||
eventName: N,
|
||||
listener: (arg: E[typeof eventName]) => void
|
||||
): this {
|
||||
return this.on(eventName, listener)
|
||||
}
|
||||
|
||||
/**
|
||||
* Alias for `emitter.off(eventName, listener)`.
|
||||
*
|
||||
* @since 1.1.0
|
||||
*/
|
||||
removeListener<N extends keyof E>(
|
||||
eventName: N,
|
||||
listener: (arg: E[typeof eventName]) => void
|
||||
): this {
|
||||
return this.off(eventName, listener)
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds the `listener` function to the end of the listeners array for the
|
||||
* event named `eventName`. No checks are made to see if the `listener` has
|
||||
* already been added. Multiple calls passing the same combination of `eventName`and `listener` will result in the `listener` being added, and called, multiple
|
||||
* times.
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
on<N extends keyof E>(
|
||||
eventName: N,
|
||||
listener: (arg: E[typeof eventName]) => void
|
||||
): this {
|
||||
if (eventName in this.eventListeners) {
|
||||
// eslint-disable-next-line security/detect-object-injection
|
||||
this.eventListeners[eventName].push(listener)
|
||||
} else {
|
||||
// eslint-disable-next-line security/detect-object-injection
|
||||
this.eventListeners[eventName] = [listener]
|
||||
}
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds a **one-time**`listener` function for the event named `eventName`. The
|
||||
* next time `eventName` is triggered, this listener is removed and then invoked.
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 1.1.0
|
||||
*/
|
||||
once<N extends keyof E>(
|
||||
eventName: N,
|
||||
listener: (arg: E[typeof eventName]) => void
|
||||
): this {
|
||||
const wrapper = (arg: E[typeof eventName]): void => {
|
||||
this.removeListener(eventName, wrapper)
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
|
||||
listener(arg)
|
||||
}
|
||||
return this.addListener(eventName, wrapper)
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes the all specified listener from the listener array for the event eventName
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 1.1.0
|
||||
*/
|
||||
off<N extends keyof E>(
|
||||
eventName: N,
|
||||
listener: (arg: E[typeof eventName]) => void
|
||||
): this {
|
||||
if (eventName in this.eventListeners) {
|
||||
// eslint-disable-next-line security/detect-object-injection
|
||||
this.eventListeners[eventName] = this.eventListeners[eventName].filter(
|
||||
(l) => l !== listener
|
||||
)
|
||||
}
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes all listeners, or those of the specified eventName.
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 1.1.0
|
||||
*/
|
||||
removeAllListeners<N extends keyof E>(event?: N): this {
|
||||
if (event) {
|
||||
// eslint-disable-next-line @typescript-eslint/no-dynamic-delete,security/detect-object-injection
|
||||
delete this.eventListeners[event]
|
||||
} else {
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
|
||||
this.eventListeners = Object.create(null)
|
||||
}
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* @ignore
|
||||
* Synchronously calls each of the listeners registered for the event named`eventName`, in the order they were registered, passing the supplied arguments
|
||||
* to each.
|
||||
*
|
||||
* @returns `true` if the event had listeners, `false` otherwise.
|
||||
*/
|
||||
emit<N extends keyof E>(eventName: N, arg: E[typeof eventName]): boolean {
|
||||
if (eventName in this.eventListeners) {
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment,security/detect-object-injection
|
||||
const listeners = this.eventListeners[eventName]
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
|
||||
for (const listener of listeners) listener(arg)
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the number of listeners listening to the event named `eventName`.
|
||||
*
|
||||
* @since 1.1.0
|
||||
*/
|
||||
listenerCount<N extends keyof E>(eventName: N): number {
|
||||
if (eventName in this.eventListeners)
|
||||
// eslint-disable-next-line security/detect-object-injection
|
||||
return this.eventListeners[eventName].length
|
||||
return 0
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds the `listener` function to the _beginning_ of the listeners array for the
|
||||
* event named `eventName`. No checks are made to see if the `listener` has
|
||||
* already been added. Multiple calls passing the same combination of `eventName`and `listener` will result in the `listener` being added, and called, multiple
|
||||
* times.
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 1.1.0
|
||||
*/
|
||||
prependListener<N extends keyof E>(
|
||||
eventName: N,
|
||||
listener: (arg: E[typeof eventName]) => void
|
||||
): this {
|
||||
if (eventName in this.eventListeners) {
|
||||
// eslint-disable-next-line security/detect-object-injection
|
||||
this.eventListeners[eventName].unshift(listener)
|
||||
} else {
|
||||
// eslint-disable-next-line security/detect-object-injection
|
||||
this.eventListeners[eventName] = [listener]
|
||||
}
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds a **one-time**`listener` function for the event named `eventName` to the_beginning_ of the listeners array. The next time `eventName` is triggered, this
|
||||
* listener is removed, and then invoked.
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 1.1.0
|
||||
*/
|
||||
prependOnceListener<N extends keyof E>(
|
||||
eventName: N,
|
||||
listener: (arg: E[typeof eventName]) => void
|
||||
): this {
|
||||
const wrapper = (arg: any): void => {
|
||||
this.removeListener(eventName, wrapper)
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
|
||||
listener(arg)
|
||||
}
|
||||
return this.prependListener(eventName, wrapper)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @since 1.1.0
|
||||
*/
|
||||
class Child {
|
||||
/** The child process `pid`. */
|
||||
pid: number
|
||||
|
||||
constructor(pid: number) {
|
||||
this.pid = pid
|
||||
}
|
||||
|
||||
/**
|
||||
* Writes `data` to the `stdin`.
|
||||
*
|
||||
* @param data The message to write, either a string or a byte array.
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from 'tauri-plugin-shell-api';
|
||||
* const command = Command.create('node');
|
||||
* const child = await command.spawn();
|
||||
* await child.write('message');
|
||||
* await child.write([0, 1, 2, 3, 4, 5]);
|
||||
* ```
|
||||
*
|
||||
* @returns A promise indicating the success or failure of the operation.
|
||||
*/
|
||||
async write(data: IOPayload): Promise<void> {
|
||||
return invoke('plugin:shell|stdin_write', {
|
||||
pid: this.pid,
|
||||
// correctly serialize Uint8Arrays
|
||||
buffer: typeof data === 'string' ? data : Array.from(data)
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Kills the child process.
|
||||
*
|
||||
* @returns A promise indicating the success or failure of the operation.
|
||||
*/
|
||||
async kill(): Promise<void> {
|
||||
return invoke('plugin:shell|kill', {
|
||||
cmd: 'killChild',
|
||||
pid: this.pid
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
interface CommandEvents {
|
||||
close: TerminatedPayload
|
||||
error: string
|
||||
}
|
||||
|
||||
interface OutputEvents<O extends IOPayload> {
|
||||
data: O
|
||||
}
|
||||
|
||||
/**
|
||||
* The entry point for spawning child processes.
|
||||
* It emits the `close` and `error` events.
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from 'tauri-plugin-shell-api';
|
||||
* const command = Command.create('node');
|
||||
* command.on('close', data => {
|
||||
* console.log(`command finished with code ${data.code} and signal ${data.signal}`)
|
||||
* });
|
||||
* command.on('error', error => console.error(`command error: "${error}"`));
|
||||
* command.stdout.on('data', line => console.log(`command stdout: "${line}"`));
|
||||
* command.stderr.on('data', line => console.log(`command stderr: "${line}"`));
|
||||
*
|
||||
* const child = await command.spawn();
|
||||
* console.log('pid:', child.pid);
|
||||
* ```
|
||||
*
|
||||
* @since 1.1.0
|
||||
*
|
||||
*/
|
||||
class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
/** @ignore Program to execute. */
|
||||
private readonly program: string
|
||||
/** @ignore Program arguments */
|
||||
private readonly args: string[]
|
||||
/** @ignore Spawn options. */
|
||||
private readonly options: InternalSpawnOptions
|
||||
/** Event emitter for the `stdout`. Emits the `data` event. */
|
||||
readonly stdout = new EventEmitter<OutputEvents<O>>()
|
||||
/** Event emitter for the `stderr`. Emits the `data` event. */
|
||||
readonly stderr = new EventEmitter<OutputEvents<O>>()
|
||||
|
||||
/**
|
||||
* @ignore
|
||||
* Creates a new `Command` instance.
|
||||
*
|
||||
* @param program The program name to execute.
|
||||
* It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`.
|
||||
* @param args Program arguments.
|
||||
* @param options Spawn options.
|
||||
*/
|
||||
private constructor(
|
||||
program: string,
|
||||
args: string | string[] = [],
|
||||
options?: SpawnOptions
|
||||
) {
|
||||
super()
|
||||
this.program = program
|
||||
this.args = typeof args === 'string' ? [args] : args
|
||||
this.options = options ?? {}
|
||||
}
|
||||
|
||||
static create(program: string, args?: string | string[]): Command<string>
|
||||
static create(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions & { encoding: 'raw' }
|
||||
): Command<Uint8Array>
|
||||
static create(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions
|
||||
): Command<string>
|
||||
|
||||
/**
|
||||
* Creates a command to execute the given program.
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from 'tauri-plugin-shell-api';
|
||||
* const command = Command.create('my-app', ['run', 'tauri']);
|
||||
* const output = await command.execute();
|
||||
* ```
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`.
|
||||
*/
|
||||
static create<O extends IOPayload>(
|
||||
program: string,
|
||||
args: string | string[] = [],
|
||||
options?: SpawnOptions
|
||||
): Command<O> {
|
||||
return new Command(program, args, options)
|
||||
}
|
||||
|
||||
static sidecar(program: string, args?: string | string[]): Command<string>
|
||||
static sidecar(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions & { encoding: 'raw' }
|
||||
): Command<Uint8Array>
|
||||
static sidecar(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions
|
||||
): Command<string>
|
||||
|
||||
/**
|
||||
* Creates a command to execute the given sidecar program.
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from 'tauri-plugin-shell-api';
|
||||
* const command = Command.sidecar('my-sidecar');
|
||||
* const output = await command.execute();
|
||||
* ```
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`.
|
||||
*/
|
||||
static sidecar<O extends IOPayload>(
|
||||
program: string,
|
||||
args: string | string[] = [],
|
||||
options?: SpawnOptions
|
||||
): Command<O> {
|
||||
const instance = new Command<O>(program, args, options)
|
||||
instance.options.sidecar = true
|
||||
return instance
|
||||
}
|
||||
|
||||
/**
|
||||
* Executes the command as a child process, returning a handle to it.
|
||||
*
|
||||
* @returns A promise resolving to the child process handle.
|
||||
*/
|
||||
async spawn(): Promise<Child> {
|
||||
return execute<O>(
|
||||
(event) => {
|
||||
switch (event.event) {
|
||||
case 'Error':
|
||||
this.emit('error', event.payload)
|
||||
break
|
||||
case 'Terminated':
|
||||
this.emit('close', event.payload)
|
||||
break
|
||||
case 'Stdout':
|
||||
this.stdout.emit('data', event.payload)
|
||||
break
|
||||
case 'Stderr':
|
||||
this.stderr.emit('data', event.payload)
|
||||
break
|
||||
}
|
||||
},
|
||||
this.program,
|
||||
this.args,
|
||||
this.options
|
||||
).then((pid) => new Child(pid))
|
||||
}
|
||||
|
||||
/**
|
||||
* Executes the command as a child process, waiting for it to finish and collecting all of its output.
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from 'tauri-plugin-shell-api';
|
||||
* const output = await Command.create('echo', 'message').execute();
|
||||
* assert(output.code === 0);
|
||||
* assert(output.signal === null);
|
||||
* assert(output.stdout === 'message');
|
||||
* assert(output.stderr === '');
|
||||
* ```
|
||||
*
|
||||
* @returns A promise resolving to the child process output.
|
||||
*/
|
||||
async execute(): Promise<ChildProcess<O>> {
|
||||
return new Promise((resolve, reject) => {
|
||||
this.on('error', reject)
|
||||
|
||||
const stdout: O[] = []
|
||||
const stderr: O[] = []
|
||||
this.stdout.on('data', (line: O) => {
|
||||
stdout.push(line)
|
||||
})
|
||||
this.stderr.on('data', (line: O) => {
|
||||
stderr.push(line)
|
||||
})
|
||||
|
||||
this.on('close', (payload: TerminatedPayload) => {
|
||||
resolve({
|
||||
code: payload.code,
|
||||
signal: payload.signal,
|
||||
stdout: this.collectOutput(stdout) as O,
|
||||
stderr: this.collectOutput(stderr) as O
|
||||
})
|
||||
})
|
||||
|
||||
this.spawn().catch(reject)
|
||||
})
|
||||
}
|
||||
|
||||
/** @ignore */
|
||||
private collectOutput(events: O[]): string | Uint8Array {
|
||||
if (this.options.encoding === 'raw') {
|
||||
return events.reduce<Uint8Array>((p, c) => {
|
||||
return new Uint8Array([...p, ...(c as Uint8Array), 10])
|
||||
}, new Uint8Array())
|
||||
} else {
|
||||
return events.join('\n')
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Describes the event message received from the command.
|
||||
*/
|
||||
interface Event<T, V> {
|
||||
event: T
|
||||
payload: V
|
||||
}
|
||||
|
||||
/**
|
||||
* Payload for the `Terminated` command event.
|
||||
*/
|
||||
interface TerminatedPayload {
|
||||
/** Exit code of the process. `null` if the process was terminated by a signal on Unix. */
|
||||
code: number | null
|
||||
/** If the process was terminated by a signal, represents that signal. */
|
||||
signal: number | null
|
||||
}
|
||||
|
||||
/** Event payload type */
|
||||
type IOPayload = string | Uint8Array
|
||||
|
||||
/** Events emitted by the child process. */
|
||||
type CommandEvent<O extends IOPayload> =
|
||||
| Event<'Stdout', O>
|
||||
| Event<'Stderr', O>
|
||||
| Event<'Terminated', TerminatedPayload>
|
||||
| Event<'Error', string>
|
||||
|
||||
/**
|
||||
* Opens a path or URL with the system's default app,
|
||||
* or the one specified with `openWith`.
|
||||
*
|
||||
* The `openWith` value must be one of `firefox`, `google chrome`, `chromium` `safari`,
|
||||
* `open`, `start`, `xdg-open`, `gio`, `gnome-open`, `kde-open` or `wslview`.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { open } from 'tauri-plugin-shell-api';
|
||||
* // opens the given URL on the default browser:
|
||||
* await open('https://github.com/tauri-apps/tauri');
|
||||
* // opens the given URL using `firefox`:
|
||||
* await open('https://github.com/tauri-apps/tauri', 'firefox');
|
||||
* // opens a file using the default program:
|
||||
* await open('/path/to/file');
|
||||
* ```
|
||||
*
|
||||
* @param path The path or URL to open.
|
||||
* This value is matched against the string regex defined on `tauri.conf.json > tauri > allowlist > shell > open`,
|
||||
* which defaults to `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+`.
|
||||
* @param openWith The app to open the file or URL with.
|
||||
* Defaults to the system default application for the specified path type.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
async function open(path: string, openWith?: string): Promise<void> {
|
||||
return invoke('plugin:shell|open', {
|
||||
path,
|
||||
with: openWith
|
||||
})
|
||||
}
|
||||
|
||||
export { Command, Child, EventEmitter, open }
|
||||
export type {
|
||||
IOPayload,
|
||||
CommandEvents,
|
||||
TerminatedPayload,
|
||||
OutputEvents,
|
||||
ChildProcess,
|
||||
SpawnOptions
|
||||
}
|
||||
@ -0,0 +1,32 @@
|
||||
{
|
||||
"name": "tauri-plugin-shell-api",
|
||||
"version": "0.0.0",
|
||||
"license": "MIT or APACHE-2.0",
|
||||
"authors": [
|
||||
"Tauri Programme within The Commons Conservancy"
|
||||
],
|
||||
"type": "module",
|
||||
"browser": "dist-js/index.min.js",
|
||||
"module": "dist-js/index.mjs",
|
||||
"types": "dist-js/index.d.ts",
|
||||
"exports": {
|
||||
"import": "./dist-js/index.mjs",
|
||||
"types": "./dist-js/index.d.ts",
|
||||
"browser": "./dist-js/index.min.js"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "rollup -c"
|
||||
},
|
||||
"files": [
|
||||
"dist-js",
|
||||
"!dist-js/**/*.map",
|
||||
"README.md",
|
||||
"LICENSE"
|
||||
],
|
||||
"devDependencies": {
|
||||
"tslib": "^2.4.1"
|
||||
},
|
||||
"dependencies": {
|
||||
"@tauri-apps/api": "^1.2.0"
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,11 @@
|
||||
import { readFileSync } from "fs";
|
||||
|
||||
import { createConfig } from "../../shared/rollup.config.mjs";
|
||||
|
||||
export default createConfig({
|
||||
input: "guest-js/index.ts",
|
||||
pkg: JSON.parse(
|
||||
readFileSync(new URL("./package.json", import.meta.url), "utf8")
|
||||
),
|
||||
external: [/^@tauri-apps\/api/],
|
||||
});
|
||||
@ -0,0 +1,211 @@
|
||||
use std::{collections::HashMap, path::PathBuf, string::FromUtf8Error};
|
||||
|
||||
use encoding_rs::Encoding;
|
||||
use serde::{Deserialize, Serialize};
|
||||
use tauri::{api::ipc::CallbackFn, Manager, Runtime, State, Window};
|
||||
|
||||
use crate::{
|
||||
open::Program,
|
||||
process::{CommandEvent, TerminatedPayload},
|
||||
scope::ExecuteArgs,
|
||||
Shell,
|
||||
};
|
||||
|
||||
type ChildId = u32;
|
||||
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
#[serde(tag = "event", content = "payload")]
|
||||
#[non_exhaustive]
|
||||
enum JSCommandEvent {
|
||||
/// Stderr bytes until a newline (\n) or carriage return (\r) is found.
|
||||
Stderr(Buffer),
|
||||
/// Stdout bytes until a newline (\n) or carriage return (\r) is found.
|
||||
Stdout(Buffer),
|
||||
/// An error happened waiting for the command to finish or converting the stdout/stderr bytes to an UTF-8 string.
|
||||
Error(String),
|
||||
/// Command process terminated.
|
||||
Terminated(TerminatedPayload),
|
||||
}
|
||||
|
||||
fn get_event_buffer(line: Vec<u8>, encoding: EncodingWrapper) -> Result<Buffer, FromUtf8Error> {
|
||||
match encoding {
|
||||
EncodingWrapper::Text(character_encoding) => match character_encoding {
|
||||
Some(encoding) => Ok(Buffer::Text(
|
||||
encoding.decode_with_bom_removal(&line).0.into(),
|
||||
)),
|
||||
None => String::from_utf8(line).map(Buffer::Text),
|
||||
},
|
||||
EncodingWrapper::Raw => Ok(Buffer::Raw(line)),
|
||||
}
|
||||
}
|
||||
|
||||
impl JSCommandEvent {
|
||||
pub fn new(event: CommandEvent, encoding: EncodingWrapper) -> Self {
|
||||
match event {
|
||||
CommandEvent::Terminated(payload) => JSCommandEvent::Terminated(payload),
|
||||
CommandEvent::Error(error) => JSCommandEvent::Error(error),
|
||||
CommandEvent::Stderr(line) => get_event_buffer(line, encoding)
|
||||
.map(JSCommandEvent::Stderr)
|
||||
.unwrap_or_else(|e| JSCommandEvent::Error(e.to_string())),
|
||||
CommandEvent::Stdout(line) => get_event_buffer(line, encoding)
|
||||
.map(JSCommandEvent::Stdout)
|
||||
.unwrap_or_else(|e| JSCommandEvent::Error(e.to_string())),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Deserialize, Serialize)]
|
||||
#[serde(untagged)]
|
||||
#[allow(missing_docs)]
|
||||
pub enum Buffer {
|
||||
Text(String),
|
||||
Raw(Vec<u8>),
|
||||
}
|
||||
|
||||
#[derive(Debug, Copy, Clone)]
|
||||
pub enum EncodingWrapper {
|
||||
Raw,
|
||||
Text(Option<&'static Encoding>),
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Default, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct CommandOptions {
|
||||
#[serde(default)]
|
||||
sidecar: bool,
|
||||
cwd: Option<PathBuf>,
|
||||
// by default we don't add any env variables to the spawned process
|
||||
// but the env is an `Option` so when it's `None` we clear the env.
|
||||
#[serde(default = "default_env")]
|
||||
env: Option<HashMap<String, String>>,
|
||||
// Character encoding for stdout/stderr
|
||||
encoding: Option<String>,
|
||||
}
|
||||
|
||||
#[allow(clippy::unnecessary_wraps)]
|
||||
fn default_env() -> Option<HashMap<String, String>> {
|
||||
Some(HashMap::default())
|
||||
}
|
||||
|
||||
#[tauri::command]
|
||||
pub fn execute<R: Runtime>(
|
||||
window: Window<R>,
|
||||
shell: State<'_, Shell<R>>,
|
||||
program: String,
|
||||
args: ExecuteArgs,
|
||||
on_event_fn: CallbackFn,
|
||||
options: CommandOptions,
|
||||
) -> crate::Result<ChildId> {
|
||||
let mut command = if options.sidecar {
|
||||
let program = PathBuf::from(program);
|
||||
let program_as_string = program.display().to_string();
|
||||
let program_no_ext_as_string = program.with_extension("").display().to_string();
|
||||
let configured_sidecar = window
|
||||
.config()
|
||||
.tauri
|
||||
.bundle
|
||||
.external_bin
|
||||
.as_ref()
|
||||
.and_then(|bins| {
|
||||
bins.iter()
|
||||
.find(|b| b == &&program_as_string || b == &&program_no_ext_as_string)
|
||||
})
|
||||
.cloned();
|
||||
if let Some(sidecar) = configured_sidecar {
|
||||
shell
|
||||
.scope
|
||||
.prepare_sidecar(&program.to_string_lossy(), &sidecar, args)?
|
||||
} else {
|
||||
return Err(crate::Error::SidecarNotAllowed(program));
|
||||
}
|
||||
} else {
|
||||
match shell.scope.prepare(&program, args) {
|
||||
Ok(cmd) => cmd,
|
||||
Err(e) => {
|
||||
#[cfg(debug_assertions)]
|
||||
eprintln!("{e}");
|
||||
return Err(crate::Error::ProgramNotAllowed(PathBuf::from(program)));
|
||||
}
|
||||
}
|
||||
};
|
||||
if let Some(cwd) = options.cwd {
|
||||
command = command.current_dir(cwd);
|
||||
}
|
||||
if let Some(env) = options.env {
|
||||
command = command.envs(env);
|
||||
} else {
|
||||
command = command.env_clear();
|
||||
}
|
||||
let encoding = match options.encoding {
|
||||
Option::None => EncodingWrapper::Text(None),
|
||||
Some(encoding) => match encoding.as_str() {
|
||||
"raw" => EncodingWrapper::Raw,
|
||||
_ => {
|
||||
if let Some(text_encoding) = Encoding::for_label(encoding.as_bytes()) {
|
||||
EncodingWrapper::Text(Some(text_encoding))
|
||||
} else {
|
||||
return Err(crate::Error::UnknownEncoding(encoding));
|
||||
}
|
||||
}
|
||||
},
|
||||
};
|
||||
|
||||
let (mut rx, child) = command.spawn()?;
|
||||
|
||||
let pid = child.pid();
|
||||
shell.children.lock().unwrap().insert(pid, child);
|
||||
let children = shell.children.clone();
|
||||
|
||||
tauri::async_runtime::spawn(async move {
|
||||
while let Some(event) = rx.recv().await {
|
||||
if matches!(event, crate::process::CommandEvent::Terminated(_)) {
|
||||
children.lock().unwrap().remove(&pid);
|
||||
};
|
||||
let js_event = JSCommandEvent::new(event, encoding);
|
||||
let js = tauri::api::ipc::format_callback(on_event_fn, &js_event)
|
||||
.expect("unable to serialize CommandEvent");
|
||||
|
||||
let _ = window.eval(js.as_str());
|
||||
}
|
||||
});
|
||||
|
||||
Ok(pid)
|
||||
}
|
||||
|
||||
#[tauri::command]
|
||||
pub fn stdin_write<R: Runtime>(
|
||||
_window: Window<R>,
|
||||
shell: State<'_, Shell<R>>,
|
||||
pid: ChildId,
|
||||
buffer: Buffer,
|
||||
) -> crate::Result<()> {
|
||||
if let Some(child) = shell.children.lock().unwrap().get_mut(&pid) {
|
||||
match buffer {
|
||||
Buffer::Text(t) => child.write(t.as_bytes())?,
|
||||
Buffer::Raw(r) => child.write(&r)?,
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[tauri::command]
|
||||
pub fn kill<R: Runtime>(
|
||||
_window: Window<R>,
|
||||
shell: State<'_, Shell<R>>,
|
||||
pid: ChildId,
|
||||
) -> crate::Result<()> {
|
||||
if let Some(child) = shell.children.lock().unwrap().remove(&pid) {
|
||||
child.kill()?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[tauri::command]
|
||||
pub fn open<R: Runtime>(
|
||||
_window: Window<R>,
|
||||
shell: State<'_, Shell<R>>,
|
||||
path: String,
|
||||
with: Option<Program>,
|
||||
) -> crate::Result<()> {
|
||||
shell.open(path, with)
|
||||
}
|
||||
@ -0,0 +1,32 @@
|
||||
use std::path::PathBuf;
|
||||
|
||||
use serde::{Serialize, Serializer};
|
||||
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum Error {
|
||||
#[error(transparent)]
|
||||
Io(#[from] std::io::Error),
|
||||
#[error("current executable path has no parent")]
|
||||
CurrentExeHasNoParent,
|
||||
#[error("unknown program {0}")]
|
||||
UnknownProgramName(String),
|
||||
#[error(transparent)]
|
||||
Scope(#[from] crate::scope::Error),
|
||||
/// Sidecar not allowed by the configuration.
|
||||
#[error("sidecar not configured under `tauri.conf.json > tauri > bundle > externalBin`: {0}")]
|
||||
SidecarNotAllowed(PathBuf),
|
||||
/// Program not allowed by the scope.
|
||||
#[error("program not allowed on the configured shell scope: {0}")]
|
||||
ProgramNotAllowed(PathBuf),
|
||||
#[error("unknown encoding {0}")]
|
||||
UnknownEncoding(String),
|
||||
}
|
||||
|
||||
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())
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,156 @@
|
||||
use std::{
|
||||
collections::HashMap,
|
||||
sync::{Arc, Mutex},
|
||||
};
|
||||
|
||||
use process::{Command, CommandChild};
|
||||
use regex::Regex;
|
||||
use scope::{Scope, ScopeAllowedCommand, ScopeConfig};
|
||||
use tauri::{
|
||||
plugin::{Builder, TauriPlugin},
|
||||
utils::config::{ShellAllowedArg, ShellAllowedArgs, ShellAllowlistOpen, ShellAllowlistScope},
|
||||
AppHandle, Manager, RunEvent, Runtime,
|
||||
};
|
||||
|
||||
mod commands;
|
||||
mod error;
|
||||
mod open;
|
||||
pub mod process;
|
||||
mod scope;
|
||||
|
||||
pub use error::Error;
|
||||
type Result<T> = std::result::Result<T, Error>;
|
||||
type ChildStore = Arc<Mutex<HashMap<u32, CommandChild>>>;
|
||||
|
||||
pub struct Shell<R: Runtime> {
|
||||
#[allow(dead_code)]
|
||||
app: AppHandle<R>,
|
||||
scope: Scope,
|
||||
children: ChildStore,
|
||||
}
|
||||
|
||||
impl<R: Runtime> Shell<R> {
|
||||
/// Creates a new Command for launching the given program.
|
||||
pub fn command(&self, program: impl Into<String>) -> Command {
|
||||
Command::new(program)
|
||||
}
|
||||
|
||||
/// Creates a new Command for launching the given sidecar program.
|
||||
///
|
||||
/// A sidecar program is a embedded external binary in order to make your application work
|
||||
/// or to prevent users having to install additional dependencies (e.g. Node.js, Python, etc).
|
||||
pub fn sidecar(&self, program: impl Into<String>) -> Result<Command> {
|
||||
Command::new_sidecar(program)
|
||||
}
|
||||
|
||||
/// Open a (url) path with a default or specific browser opening program.
|
||||
///
|
||||
/// See [`crate::api::shell::open`] for how it handles security-related measures.
|
||||
pub fn open(&self, path: String, with: Option<open::Program>) -> Result<()> {
|
||||
open::open(&self.scope, path, with).map_err(Into::into)
|
||||
}
|
||||
}
|
||||
|
||||
pub trait ShellExt<R: Runtime> {
|
||||
fn shell(&self) -> &Shell<R>;
|
||||
}
|
||||
|
||||
impl<R: Runtime, T: Manager<R>> ShellExt<R> for T {
|
||||
fn shell(&self) -> &Shell<R> {
|
||||
self.state::<Shell<R>>().inner()
|
||||
}
|
||||
}
|
||||
|
||||
pub fn init<R: Runtime>() -> TauriPlugin<R> {
|
||||
Builder::new("shell")
|
||||
.invoke_handler(tauri::generate_handler![
|
||||
commands::execute,
|
||||
commands::stdin_write,
|
||||
commands::kill,
|
||||
commands::open
|
||||
])
|
||||
.setup(|app, _api| {
|
||||
app.manage(Shell {
|
||||
app: app.clone(),
|
||||
children: Default::default(),
|
||||
scope: Scope::new(
|
||||
app,
|
||||
shell_scope(
|
||||
app.config().tauri.allowlist.shell.scope.clone(),
|
||||
&app.config().tauri.allowlist.shell.open,
|
||||
),
|
||||
),
|
||||
});
|
||||
Ok(())
|
||||
})
|
||||
.on_event(|app, event| {
|
||||
if let RunEvent::Exit = event {
|
||||
let shell = app.state::<Shell<R>>();
|
||||
let children = {
|
||||
let mut lock = shell.children.lock().unwrap();
|
||||
std::mem::take(&mut *lock)
|
||||
};
|
||||
for child in children.into_values() {
|
||||
let _ = child.kill();
|
||||
}
|
||||
}
|
||||
})
|
||||
.build()
|
||||
}
|
||||
|
||||
fn shell_scope(scope: ShellAllowlistScope, open: &ShellAllowlistOpen) -> ScopeConfig {
|
||||
let shell_scopes = get_allowed_clis(scope);
|
||||
|
||||
let shell_scope_open = match open {
|
||||
ShellAllowlistOpen::Flag(false) => None,
|
||||
ShellAllowlistOpen::Flag(true) => {
|
||||
Some(Regex::new(r#"^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+"#).unwrap())
|
||||
}
|
||||
ShellAllowlistOpen::Validate(validator) => {
|
||||
let validator =
|
||||
Regex::new(validator).unwrap_or_else(|e| panic!("invalid regex {validator}: {e}"));
|
||||
Some(validator)
|
||||
}
|
||||
_ => panic!("unknown shell open format, unable to prepare"),
|
||||
};
|
||||
|
||||
ScopeConfig {
|
||||
open: shell_scope_open,
|
||||
scopes: shell_scopes,
|
||||
}
|
||||
}
|
||||
|
||||
fn get_allowed_clis(scope: ShellAllowlistScope) -> HashMap<String, ScopeAllowedCommand> {
|
||||
scope
|
||||
.0
|
||||
.into_iter()
|
||||
.map(|scope| {
|
||||
let args = match scope.args {
|
||||
ShellAllowedArgs::Flag(true) => None,
|
||||
ShellAllowedArgs::Flag(false) => Some(Vec::new()),
|
||||
ShellAllowedArgs::List(list) => {
|
||||
let list = list.into_iter().map(|arg| match arg {
|
||||
ShellAllowedArg::Fixed(fixed) => scope::ScopeAllowedArg::Fixed(fixed),
|
||||
ShellAllowedArg::Var { validator } => {
|
||||
let validator = Regex::new(&validator)
|
||||
.unwrap_or_else(|e| panic!("invalid regex {validator}: {e}"));
|
||||
scope::ScopeAllowedArg::Var { validator }
|
||||
}
|
||||
_ => panic!("unknown shell scope arg, unable to prepare"),
|
||||
});
|
||||
Some(list.collect())
|
||||
}
|
||||
_ => panic!("unknown shell scope command, unable to prepare"),
|
||||
};
|
||||
|
||||
(
|
||||
scope.name,
|
||||
ScopeAllowedCommand {
|
||||
command: scope.command,
|
||||
args,
|
||||
sidecar: scope.sidecar,
|
||||
},
|
||||
)
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
@ -0,0 +1,122 @@
|
||||
// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
//! Types and functions related to shell.
|
||||
|
||||
use serde::{Deserialize, Deserializer};
|
||||
|
||||
use crate::scope::Scope;
|
||||
use std::str::FromStr;
|
||||
|
||||
/// Program to use on the [`open()`] call.
|
||||
pub enum Program {
|
||||
/// Use the `open` program.
|
||||
Open,
|
||||
/// Use the `start` program.
|
||||
Start,
|
||||
/// Use the `xdg-open` program.
|
||||
XdgOpen,
|
||||
/// Use the `gio` program.
|
||||
Gio,
|
||||
/// Use the `gnome-open` program.
|
||||
GnomeOpen,
|
||||
/// Use the `kde-open` program.
|
||||
KdeOpen,
|
||||
/// Use the `wslview` program.
|
||||
WslView,
|
||||
/// Use the `Firefox` program.
|
||||
Firefox,
|
||||
/// Use the `Google Chrome` program.
|
||||
Chrome,
|
||||
/// Use the `Chromium` program.
|
||||
Chromium,
|
||||
/// Use the `Safari` program.
|
||||
Safari,
|
||||
}
|
||||
|
||||
impl FromStr for Program {
|
||||
type Err = super::Error;
|
||||
|
||||
fn from_str(s: &str) -> Result<Self, Self::Err> {
|
||||
let p = match s.to_lowercase().as_str() {
|
||||
"open" => Self::Open,
|
||||
"start" => Self::Start,
|
||||
"xdg-open" => Self::XdgOpen,
|
||||
"gio" => Self::Gio,
|
||||
"gnome-open" => Self::GnomeOpen,
|
||||
"kde-open" => Self::KdeOpen,
|
||||
"wslview" => Self::WslView,
|
||||
"firefox" => Self::Firefox,
|
||||
"chrome" | "google chrome" => Self::Chrome,
|
||||
"chromium" => Self::Chromium,
|
||||
"safari" => Self::Safari,
|
||||
_ => return Err(crate::Error::UnknownProgramName(s.to_string())),
|
||||
};
|
||||
Ok(p)
|
||||
}
|
||||
}
|
||||
|
||||
impl<'de> Deserialize<'de> for Program {
|
||||
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
|
||||
where
|
||||
D: Deserializer<'de>,
|
||||
{
|
||||
let s = String::deserialize(deserializer)?;
|
||||
Program::from_str(&s).map_err(|e| serde::de::Error::custom(e.to_string()))
|
||||
}
|
||||
}
|
||||
|
||||
impl Program {
|
||||
pub(crate) fn name(self) -> &'static str {
|
||||
match self {
|
||||
Self::Open => "open",
|
||||
Self::Start => "start",
|
||||
Self::XdgOpen => "xdg-open",
|
||||
Self::Gio => "gio",
|
||||
Self::GnomeOpen => "gnome-open",
|
||||
Self::KdeOpen => "kde-open",
|
||||
Self::WslView => "wslview",
|
||||
|
||||
#[cfg(target_os = "macos")]
|
||||
Self::Firefox => "Firefox",
|
||||
#[cfg(not(target_os = "macos"))]
|
||||
Self::Firefox => "firefox",
|
||||
|
||||
#[cfg(target_os = "macos")]
|
||||
Self::Chrome => "Google Chrome",
|
||||
#[cfg(not(target_os = "macos"))]
|
||||
Self::Chrome => "google-chrome",
|
||||
|
||||
#[cfg(target_os = "macos")]
|
||||
Self::Chromium => "Chromium",
|
||||
#[cfg(not(target_os = "macos"))]
|
||||
Self::Chromium => "chromium",
|
||||
|
||||
#[cfg(target_os = "macos")]
|
||||
Self::Safari => "Safari",
|
||||
#[cfg(not(target_os = "macos"))]
|
||||
Self::Safari => "safari",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Opens path or URL with the program specified in `with`, or system default if `None`.
|
||||
///
|
||||
/// The path will be matched against the shell open validation regex, defaulting to `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+`.
|
||||
/// A custom validation regex may be supplied in the config in `tauri > allowlist > scope > open`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use tauri_plugin_shell::ShellExt;
|
||||
/// tauri::Builder::default()
|
||||
/// .setup(|app| {
|
||||
/// // open the given URL on the system default browser
|
||||
/// app.shell().open("https://github.com/tauri-apps/tauri", None)?;
|
||||
/// Ok(())
|
||||
/// });
|
||||
/// ```
|
||||
pub fn open<P: AsRef<str>>(scope: &Scope, path: P, with: Option<Program>) -> crate::Result<()> {
|
||||
scope.open(path.as_ref(), with).map_err(Into::into)
|
||||
}
|
||||
@ -0,0 +1,504 @@
|
||||
// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
use std::{
|
||||
collections::HashMap,
|
||||
io::{BufReader, Write},
|
||||
path::PathBuf,
|
||||
process::{Command as StdCommand, Stdio},
|
||||
sync::{Arc, RwLock},
|
||||
thread::spawn,
|
||||
};
|
||||
|
||||
#[cfg(unix)]
|
||||
use std::os::unix::process::ExitStatusExt;
|
||||
#[cfg(windows)]
|
||||
use std::os::windows::process::CommandExt;
|
||||
|
||||
#[cfg(windows)]
|
||||
const CREATE_NO_WINDOW: u32 = 0x0800_0000;
|
||||
const NEWLINE_BYTE: u8 = b'\n';
|
||||
|
||||
use tauri::async_runtime::{block_on as block_on_task, channel, Receiver, Sender};
|
||||
|
||||
pub use encoding_rs::Encoding;
|
||||
use os_pipe::{pipe, PipeReader, PipeWriter};
|
||||
use serde::Serialize;
|
||||
use shared_child::SharedChild;
|
||||
use tauri::utils::platform;
|
||||
|
||||
/// Payload for the [`CommandEvent::Terminated`] command event.
|
||||
#[derive(Debug, Clone, Serialize)]
|
||||
pub struct TerminatedPayload {
|
||||
/// Exit code of the process.
|
||||
pub code: Option<i32>,
|
||||
/// If the process was terminated by a signal, represents that signal.
|
||||
pub signal: Option<i32>,
|
||||
}
|
||||
|
||||
/// A event sent to the command callback.
|
||||
#[derive(Debug, Clone)]
|
||||
#[non_exhaustive]
|
||||
pub enum CommandEvent {
|
||||
/// Stderr bytes until a newline (\n) or carriage return (\r) is found.
|
||||
Stderr(Vec<u8>),
|
||||
/// Stdout bytes until a newline (\n) or carriage return (\r) is found.
|
||||
Stdout(Vec<u8>),
|
||||
/// An error happened waiting for the command to finish or converting the stdout/stderr bytes to an UTF-8 string.
|
||||
Error(String),
|
||||
/// Command process terminated.
|
||||
Terminated(TerminatedPayload),
|
||||
}
|
||||
|
||||
/// The type to spawn commands.
|
||||
#[derive(Debug)]
|
||||
pub struct Command {
|
||||
program: String,
|
||||
args: Vec<String>,
|
||||
env_clear: bool,
|
||||
env: HashMap<String, String>,
|
||||
current_dir: Option<PathBuf>,
|
||||
}
|
||||
|
||||
/// Spawned child process.
|
||||
#[derive(Debug)]
|
||||
pub struct CommandChild {
|
||||
inner: Arc<SharedChild>,
|
||||
stdin_writer: PipeWriter,
|
||||
}
|
||||
|
||||
impl CommandChild {
|
||||
/// Writes to process stdin.
|
||||
pub fn write(&mut self, buf: &[u8]) -> crate::Result<()> {
|
||||
self.stdin_writer.write_all(buf)?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Sends a kill signal to the child.
|
||||
pub fn kill(self) -> crate::Result<()> {
|
||||
self.inner.kill()?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Returns the process pid.
|
||||
pub fn pid(&self) -> u32 {
|
||||
self.inner.id()
|
||||
}
|
||||
}
|
||||
|
||||
/// Describes the result of a process after it has terminated.
|
||||
#[derive(Debug)]
|
||||
pub struct ExitStatus {
|
||||
code: Option<i32>,
|
||||
}
|
||||
|
||||
impl ExitStatus {
|
||||
/// Returns the exit code of the process, if any.
|
||||
pub fn code(&self) -> Option<i32> {
|
||||
self.code
|
||||
}
|
||||
|
||||
/// Returns true if exit status is zero. Signal termination is not considered a success, and success is defined as a zero exit status.
|
||||
pub fn success(&self) -> bool {
|
||||
self.code == Some(0)
|
||||
}
|
||||
}
|
||||
|
||||
/// The output of a finished process.
|
||||
#[derive(Debug)]
|
||||
pub struct Output {
|
||||
/// The status (exit code) of the process.
|
||||
pub status: ExitStatus,
|
||||
/// The data that the process wrote to stdout.
|
||||
pub stdout: Vec<u8>,
|
||||
/// The data that the process wrote to stderr.
|
||||
pub stderr: Vec<u8>,
|
||||
}
|
||||
|
||||
fn relative_command_path(command: String) -> crate::Result<String> {
|
||||
match platform::current_exe()?.parent() {
|
||||
#[cfg(windows)]
|
||||
Some(exe_dir) => Ok(format!("{}\\{command}.exe", exe_dir.display())),
|
||||
#[cfg(not(windows))]
|
||||
Some(exe_dir) => Ok(format!("{}/{command}", exe_dir.display())),
|
||||
None => Err(crate::Error::CurrentExeHasNoParent),
|
||||
}
|
||||
}
|
||||
|
||||
impl From<Command> for StdCommand {
|
||||
fn from(cmd: Command) -> StdCommand {
|
||||
let mut command = StdCommand::new(cmd.program);
|
||||
command.args(cmd.args);
|
||||
command.stdout(Stdio::piped());
|
||||
command.stdin(Stdio::piped());
|
||||
command.stderr(Stdio::piped());
|
||||
if cmd.env_clear {
|
||||
command.env_clear();
|
||||
}
|
||||
command.envs(cmd.env);
|
||||
if let Some(current_dir) = cmd.current_dir {
|
||||
command.current_dir(current_dir);
|
||||
}
|
||||
#[cfg(windows)]
|
||||
command.creation_flags(CREATE_NO_WINDOW);
|
||||
command
|
||||
}
|
||||
}
|
||||
|
||||
impl Command {
|
||||
pub(crate) fn new<S: Into<String>>(program: S) -> Self {
|
||||
Self {
|
||||
program: program.into(),
|
||||
args: Default::default(),
|
||||
env_clear: false,
|
||||
env: Default::default(),
|
||||
current_dir: None,
|
||||
}
|
||||
}
|
||||
|
||||
pub(crate) fn new_sidecar<S: Into<String>>(program: S) -> crate::Result<Self> {
|
||||
Ok(Self::new(relative_command_path(program.into())?))
|
||||
}
|
||||
|
||||
/// Appends arguments to the command.
|
||||
#[must_use]
|
||||
pub fn args<I, S>(mut self, args: I) -> Self
|
||||
where
|
||||
I: IntoIterator<Item = S>,
|
||||
S: AsRef<str>,
|
||||
{
|
||||
for arg in args {
|
||||
self.args.push(arg.as_ref().to_string());
|
||||
}
|
||||
self
|
||||
}
|
||||
|
||||
/// Clears the entire environment map for the child process.
|
||||
#[must_use]
|
||||
pub fn env_clear(mut self) -> Self {
|
||||
self.env_clear = true;
|
||||
self
|
||||
}
|
||||
|
||||
/// Adds or updates multiple environment variable mappings.
|
||||
#[must_use]
|
||||
pub fn envs(mut self, env: HashMap<String, String>) -> Self {
|
||||
self.env = env;
|
||||
self
|
||||
}
|
||||
|
||||
/// Sets the working directory for the child process.
|
||||
#[must_use]
|
||||
pub fn current_dir(mut self, current_dir: PathBuf) -> Self {
|
||||
self.current_dir.replace(current_dir);
|
||||
self
|
||||
}
|
||||
|
||||
/// Spawns the command.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use tauri::api::process::{Command, CommandEvent};
|
||||
/// tauri::async_runtime::spawn(async move {
|
||||
/// let (mut rx, mut child) = Command::new("cargo")
|
||||
/// .args(["tauri", "dev"])
|
||||
/// .spawn()
|
||||
/// .expect("Failed to spawn cargo");
|
||||
///
|
||||
/// let mut i = 0;
|
||||
/// while let Some(event) = rx.recv().await {
|
||||
/// if let CommandEvent::Stdout(line) = event {
|
||||
/// println!("got: {}", String::from_utf8(line).unwrap());
|
||||
/// i += 1;
|
||||
/// if i == 4 {
|
||||
/// child.write("message from Rust\n".as_bytes()).unwrap();
|
||||
/// i = 0;
|
||||
/// }
|
||||
/// }
|
||||
/// }
|
||||
/// });
|
||||
/// ```
|
||||
pub fn spawn(self) -> crate::Result<(Receiver<CommandEvent>, CommandChild)> {
|
||||
let mut command: StdCommand = self.into();
|
||||
let (stdout_reader, stdout_writer) = pipe()?;
|
||||
let (stderr_reader, stderr_writer) = pipe()?;
|
||||
let (stdin_reader, stdin_writer) = pipe()?;
|
||||
command.stdout(stdout_writer);
|
||||
command.stderr(stderr_writer);
|
||||
command.stdin(stdin_reader);
|
||||
|
||||
let shared_child = SharedChild::spawn(&mut command)?;
|
||||
let child = Arc::new(shared_child);
|
||||
let child_ = child.clone();
|
||||
let guard = Arc::new(RwLock::new(()));
|
||||
|
||||
//TODO commands().lock().unwrap().insert(child.id(), child.clone());
|
||||
|
||||
let (tx, rx) = channel(1);
|
||||
|
||||
spawn_pipe_reader(
|
||||
tx.clone(),
|
||||
guard.clone(),
|
||||
stdout_reader,
|
||||
CommandEvent::Stdout,
|
||||
);
|
||||
spawn_pipe_reader(
|
||||
tx.clone(),
|
||||
guard.clone(),
|
||||
stderr_reader,
|
||||
CommandEvent::Stderr,
|
||||
);
|
||||
|
||||
spawn(move || {
|
||||
let _ = match child_.wait() {
|
||||
Ok(status) => {
|
||||
let _l = guard.write().unwrap();
|
||||
//TODO commands().lock().unwrap().remove(&child_.id());
|
||||
block_on_task(async move {
|
||||
tx.send(CommandEvent::Terminated(TerminatedPayload {
|
||||
code: status.code(),
|
||||
#[cfg(windows)]
|
||||
signal: None,
|
||||
#[cfg(unix)]
|
||||
signal: status.signal(),
|
||||
}))
|
||||
.await
|
||||
})
|
||||
}
|
||||
Err(e) => {
|
||||
let _l = guard.write().unwrap();
|
||||
block_on_task(async move { tx.send(CommandEvent::Error(e.to_string())).await })
|
||||
}
|
||||
};
|
||||
});
|
||||
|
||||
Ok((
|
||||
rx,
|
||||
CommandChild {
|
||||
inner: child,
|
||||
stdin_writer,
|
||||
},
|
||||
))
|
||||
}
|
||||
|
||||
/// Executes a command as a child process, waiting for it to finish and collecting its exit status.
|
||||
/// Stdin, stdout and stderr are ignored.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```rust,no_run
|
||||
/// use tauri::api::process::Command;
|
||||
/// let status = Command::new("which").args(["ls"]).status().unwrap();
|
||||
/// println!("`which` finished with status: {:?}", status.code());
|
||||
/// ```
|
||||
pub async fn status(self) -> crate::Result<ExitStatus> {
|
||||
let (mut rx, _child) = self.spawn()?;
|
||||
let mut code = None;
|
||||
#[allow(clippy::collapsible_match)]
|
||||
while let Some(event) = rx.recv().await {
|
||||
if let CommandEvent::Terminated(payload) = event {
|
||||
code = payload.code;
|
||||
}
|
||||
}
|
||||
Ok(ExitStatus { code })
|
||||
}
|
||||
|
||||
/// Executes the command as a child process, waiting for it to finish and collecting all of its output.
|
||||
/// Stdin is ignored.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use tauri::api::process::Command;
|
||||
/// let output = Command::new("echo").args(["TAURI"]).output().unwrap();
|
||||
/// assert!(output.status.success());
|
||||
/// assert_eq!(String::from_utf8(output.stdout).unwrap(), "TAURI");
|
||||
/// ```
|
||||
pub async fn output(self) -> crate::Result<Output> {
|
||||
let (mut rx, _child) = self.spawn()?;
|
||||
|
||||
let mut code = None;
|
||||
let mut stdout = Vec::new();
|
||||
let mut stderr = Vec::new();
|
||||
|
||||
while let Some(event) = rx.recv().await {
|
||||
match event {
|
||||
CommandEvent::Terminated(payload) => {
|
||||
code = payload.code;
|
||||
}
|
||||
CommandEvent::Stdout(line) => {
|
||||
stdout.extend(line);
|
||||
stdout.push(NEWLINE_BYTE);
|
||||
}
|
||||
CommandEvent::Stderr(line) => {
|
||||
stderr.extend(line);
|
||||
stderr.push(NEWLINE_BYTE);
|
||||
}
|
||||
CommandEvent::Error(_) => {}
|
||||
}
|
||||
}
|
||||
Ok(Output {
|
||||
status: ExitStatus { code },
|
||||
stdout,
|
||||
stderr,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
fn spawn_pipe_reader<F: Fn(Vec<u8>) -> CommandEvent + Send + Copy + 'static>(
|
||||
tx: Sender<CommandEvent>,
|
||||
guard: Arc<RwLock<()>>,
|
||||
pipe_reader: PipeReader,
|
||||
wrapper: F,
|
||||
) {
|
||||
spawn(move || {
|
||||
let _lock = guard.read().unwrap();
|
||||
let mut reader = BufReader::new(pipe_reader);
|
||||
|
||||
loop {
|
||||
let mut buf = Vec::new();
|
||||
match tauri::utils::io::read_line(&mut reader, &mut buf) {
|
||||
Ok(n) => {
|
||||
if n == 0 {
|
||||
break;
|
||||
}
|
||||
let tx_ = tx.clone();
|
||||
let _ = block_on_task(async move { tx_.send(wrapper(buf)).await });
|
||||
}
|
||||
Err(e) => {
|
||||
let tx_ = tx.clone();
|
||||
let _ =
|
||||
block_on_task(
|
||||
async move { tx_.send(CommandEvent::Error(e.to_string())).await },
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// tests for the commands functions.
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
#[cfg(not(windows))]
|
||||
use super::*;
|
||||
|
||||
#[cfg(not(windows))]
|
||||
#[test]
|
||||
fn test_cmd_spawn_output() {
|
||||
let cmd = Command::new("cat").args(["test/api/test.txt"]);
|
||||
let (mut rx, _) = cmd.spawn().unwrap();
|
||||
|
||||
tauri::async_runtime::block_on(async move {
|
||||
while let Some(event) = rx.recv().await {
|
||||
match event {
|
||||
CommandEvent::Terminated(payload) => {
|
||||
assert_eq!(payload.code, Some(0));
|
||||
}
|
||||
CommandEvent::Stdout(line) => {
|
||||
assert_eq!(String::from_utf8(line).unwrap(), "This is a test doc!");
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
#[cfg(not(windows))]
|
||||
#[test]
|
||||
fn test_cmd_spawn_raw_output() {
|
||||
let cmd = Command::new("cat").args(["test/api/test.txt"]);
|
||||
let (mut rx, _) = cmd.spawn().unwrap();
|
||||
|
||||
tauri::async_runtime::block_on(async move {
|
||||
while let Some(event) = rx.recv().await {
|
||||
match event {
|
||||
CommandEvent::Terminated(payload) => {
|
||||
assert_eq!(payload.code, Some(0));
|
||||
}
|
||||
CommandEvent::Stdout(line) => {
|
||||
assert_eq!(String::from_utf8(line).unwrap(), "This is a test doc!");
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
#[cfg(not(windows))]
|
||||
#[test]
|
||||
// test the failure case
|
||||
fn test_cmd_spawn_fail() {
|
||||
let cmd = Command::new("cat").args(["test/api/"]);
|
||||
let (mut rx, _) = cmd.spawn().unwrap();
|
||||
|
||||
tauri::async_runtime::block_on(async move {
|
||||
while let Some(event) = rx.recv().await {
|
||||
match event {
|
||||
CommandEvent::Terminated(payload) => {
|
||||
assert_eq!(payload.code, Some(1));
|
||||
}
|
||||
CommandEvent::Stderr(line) => {
|
||||
assert_eq!(
|
||||
String::from_utf8(line).unwrap(),
|
||||
"cat: test/api/: Is a directory"
|
||||
);
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
#[cfg(not(windows))]
|
||||
#[test]
|
||||
// test the failure case (raw encoding)
|
||||
fn test_cmd_spawn_raw_fail() {
|
||||
let cmd = Command::new("cat").args(["test/api/"]);
|
||||
let (mut rx, _) = cmd.spawn().unwrap();
|
||||
|
||||
tauri::async_runtime::block_on(async move {
|
||||
while let Some(event) = rx.recv().await {
|
||||
match event {
|
||||
CommandEvent::Terminated(payload) => {
|
||||
assert_eq!(payload.code, Some(1));
|
||||
}
|
||||
CommandEvent::Stderr(line) => {
|
||||
assert_eq!(
|
||||
String::from_utf8(line).unwrap(),
|
||||
"cat: test/api/: Is a directory"
|
||||
);
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
#[cfg(not(windows))]
|
||||
#[test]
|
||||
fn test_cmd_output_output() {
|
||||
let cmd = Command::new("cat").args(["test/api/test.txt"]);
|
||||
let output = cmd.output().unwrap();
|
||||
|
||||
assert_eq!(String::from_utf8(output.stderr).unwrap(), "");
|
||||
assert_eq!(
|
||||
String::from_utf8(output.stdout).unwrap(),
|
||||
"This is a test doc!\n"
|
||||
);
|
||||
}
|
||||
|
||||
#[cfg(not(windows))]
|
||||
#[test]
|
||||
fn test_cmd_output_output_fail() {
|
||||
let cmd = Command::new("cat").args(["test/api/"]);
|
||||
let output = cmd.output().unwrap();
|
||||
|
||||
assert_eq!(String::from_utf8(output.stdout).unwrap(), "");
|
||||
assert_eq!(
|
||||
String::from_utf8(output.stderr).unwrap(),
|
||||
"cat: test/api/: Is a directory\n"
|
||||
);
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,272 @@
|
||||
// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
use crate::open::Program;
|
||||
use crate::process::Command;
|
||||
use crate::{Manager, Runtime};
|
||||
|
||||
use regex::Regex;
|
||||
|
||||
use std::collections::HashMap;
|
||||
|
||||
/// Allowed representation of `Execute` command arguments.
|
||||
#[derive(Debug, Clone, serde::Deserialize)]
|
||||
#[serde(untagged, deny_unknown_fields)]
|
||||
#[non_exhaustive]
|
||||
pub enum ExecuteArgs {
|
||||
/// No arguments
|
||||
None,
|
||||
|
||||
/// A single string argument
|
||||
Single(String),
|
||||
|
||||
/// Multiple string arguments
|
||||
List(Vec<String>),
|
||||
}
|
||||
|
||||
impl ExecuteArgs {
|
||||
/// Whether the argument list is empty or not.
|
||||
pub fn is_empty(&self) -> bool {
|
||||
match self {
|
||||
Self::None => true,
|
||||
Self::Single(s) if s.is_empty() => true,
|
||||
Self::List(l) => l.is_empty(),
|
||||
_ => false,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl From<()> for ExecuteArgs {
|
||||
fn from(_: ()) -> Self {
|
||||
Self::None
|
||||
}
|
||||
}
|
||||
|
||||
impl From<String> for ExecuteArgs {
|
||||
fn from(string: String) -> Self {
|
||||
Self::Single(string)
|
||||
}
|
||||
}
|
||||
|
||||
impl From<Vec<String>> for ExecuteArgs {
|
||||
fn from(vec: Vec<String>) -> Self {
|
||||
Self::List(vec)
|
||||
}
|
||||
}
|
||||
|
||||
/// Shell scope configuration.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ScopeConfig {
|
||||
/// The validation regex that `shell > open` paths must match against.
|
||||
pub open: Option<Regex>,
|
||||
|
||||
/// All allowed commands, using their unique command name as the keys.
|
||||
pub scopes: HashMap<String, ScopeAllowedCommand>,
|
||||
}
|
||||
|
||||
/// A configured scoped shell command.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ScopeAllowedCommand {
|
||||
/// The shell command to be called.
|
||||
pub command: std::path::PathBuf,
|
||||
|
||||
/// The arguments the command is allowed to be called with.
|
||||
pub args: Option<Vec<ScopeAllowedArg>>,
|
||||
|
||||
/// If this command is a sidecar command.
|
||||
pub sidecar: bool,
|
||||
}
|
||||
|
||||
/// A configured argument to a scoped shell command.
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum ScopeAllowedArg {
|
||||
/// A non-configurable argument.
|
||||
Fixed(String),
|
||||
|
||||
/// An argument with a value to be evaluated at runtime, must pass a regex validation.
|
||||
Var {
|
||||
/// The validation that the variable value must pass in order to be called.
|
||||
validator: Regex,
|
||||
},
|
||||
}
|
||||
|
||||
impl ScopeAllowedArg {
|
||||
/// If the argument is fixed.
|
||||
pub fn is_fixed(&self) -> bool {
|
||||
matches!(self, Self::Fixed(_))
|
||||
}
|
||||
}
|
||||
|
||||
/// Scope for filesystem access.
|
||||
#[derive(Clone)]
|
||||
pub struct Scope(ScopeConfig);
|
||||
|
||||
/// All errors that can happen while validating a scoped command.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum Error {
|
||||
/// At least one argument did not pass input validation.
|
||||
#[error("The scoped command was called with the improper sidecar flag set")]
|
||||
BadSidecarFlag,
|
||||
|
||||
/// The sidecar program validated but failed to find the sidecar path.
|
||||
#[error(
|
||||
"The scoped sidecar command was validated, but failed to create the path to the command: {0}"
|
||||
)]
|
||||
Sidecar(String),
|
||||
|
||||
/// The named command was not found in the scoped config.
|
||||
#[error("Scoped command {0} not found")]
|
||||
NotFound(String),
|
||||
|
||||
/// A command variable has no value set in the arguments.
|
||||
#[error(
|
||||
"Scoped command argument at position {0} must match regex validation {1} but it was not found"
|
||||
)]
|
||||
MissingVar(usize, String),
|
||||
|
||||
/// At least one argument did not pass input validation.
|
||||
#[error("Scoped command argument at position {index} was found, but failed regex validation {validation}")]
|
||||
Validation {
|
||||
/// Index of the variable.
|
||||
index: usize,
|
||||
|
||||
/// Regex that the variable value failed to match.
|
||||
validation: String,
|
||||
},
|
||||
|
||||
/// The format of the passed input does not match the expected shape.
|
||||
///
|
||||
/// This can happen from passing a string or array of strings to a command that is expecting
|
||||
/// named variables, and vice-versa.
|
||||
#[error("Scoped command {0} received arguments in an unexpected format")]
|
||||
InvalidInput(String),
|
||||
|
||||
/// A generic IO error that occurs while executing specified shell commands.
|
||||
#[error("Scoped shell IO error: {0}")]
|
||||
Io(#[from] std::io::Error),
|
||||
}
|
||||
|
||||
impl Scope {
|
||||
/// Creates a new shell scope.
|
||||
pub(crate) fn new<R: Runtime, M: Manager<R>>(manager: &M, mut scope: ScopeConfig) -> Self {
|
||||
for cmd in scope.scopes.values_mut() {
|
||||
if let Ok(path) = manager.path().parse(&cmd.command) {
|
||||
cmd.command = path;
|
||||
}
|
||||
}
|
||||
Self(scope)
|
||||
}
|
||||
|
||||
/// Validates argument inputs and creates a Tauri sidecar [`Command`].
|
||||
pub fn prepare_sidecar(
|
||||
&self,
|
||||
command_name: &str,
|
||||
command_script: &str,
|
||||
args: ExecuteArgs,
|
||||
) -> Result<Command, Error> {
|
||||
self._prepare(command_name, args, Some(command_script))
|
||||
}
|
||||
|
||||
/// Validates argument inputs and creates a Tauri [`Command`].
|
||||
pub fn prepare(&self, command_name: &str, args: ExecuteArgs) -> Result<Command, Error> {
|
||||
self._prepare(command_name, args, None)
|
||||
}
|
||||
|
||||
/// Validates argument inputs and creates a Tauri [`Command`].
|
||||
pub fn _prepare(
|
||||
&self,
|
||||
command_name: &str,
|
||||
args: ExecuteArgs,
|
||||
sidecar: Option<&str>,
|
||||
) -> Result<Command, Error> {
|
||||
let command = match self.0.scopes.get(command_name) {
|
||||
Some(command) => command,
|
||||
None => return Err(Error::NotFound(command_name.into())),
|
||||
};
|
||||
|
||||
if command.sidecar != sidecar.is_some() {
|
||||
return Err(Error::BadSidecarFlag);
|
||||
}
|
||||
|
||||
let args = match (&command.args, args) {
|
||||
(None, ExecuteArgs::None) => Ok(vec![]),
|
||||
(None, ExecuteArgs::List(list)) => Ok(list),
|
||||
(None, ExecuteArgs::Single(string)) => Ok(vec![string]),
|
||||
(Some(list), ExecuteArgs::List(args)) => list
|
||||
.iter()
|
||||
.enumerate()
|
||||
.map(|(i, arg)| match arg {
|
||||
ScopeAllowedArg::Fixed(fixed) => Ok(fixed.to_string()),
|
||||
ScopeAllowedArg::Var { validator } => {
|
||||
let value = args
|
||||
.get(i)
|
||||
.ok_or_else(|| Error::MissingVar(i, validator.to_string()))?
|
||||
.to_string();
|
||||
if validator.is_match(&value) {
|
||||
Ok(value)
|
||||
} else {
|
||||
Err(Error::Validation {
|
||||
index: i,
|
||||
validation: validator.to_string(),
|
||||
})
|
||||
}
|
||||
}
|
||||
})
|
||||
.collect(),
|
||||
(Some(list), arg) if arg.is_empty() && list.iter().all(ScopeAllowedArg::is_fixed) => {
|
||||
list.iter()
|
||||
.map(|arg| match arg {
|
||||
ScopeAllowedArg::Fixed(fixed) => Ok(fixed.to_string()),
|
||||
_ => unreachable!(),
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
(Some(list), _) if list.is_empty() => Err(Error::InvalidInput(command_name.into())),
|
||||
(Some(_), _) => Err(Error::InvalidInput(command_name.into())),
|
||||
}?;
|
||||
|
||||
let command_s = sidecar
|
||||
.map(|s| {
|
||||
std::path::PathBuf::from(s)
|
||||
.components()
|
||||
.last()
|
||||
.unwrap()
|
||||
.as_os_str()
|
||||
.to_string_lossy()
|
||||
.into_owned()
|
||||
})
|
||||
.unwrap_or_else(|| command.command.to_string_lossy().into_owned());
|
||||
let command = if command.sidecar {
|
||||
Command::new_sidecar(command_s).map_err(|e| Error::Sidecar(e.to_string()))?
|
||||
} else {
|
||||
Command::new(command_s)
|
||||
};
|
||||
|
||||
Ok(command.args(args))
|
||||
}
|
||||
|
||||
/// Open a path in the default (or specified) browser.
|
||||
///
|
||||
/// The path is validated against the `tauri > allowlist > shell > open` validation regex, which
|
||||
/// defaults to `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+`.
|
||||
pub fn open(&self, path: &str, with: Option<Program>) -> Result<(), Error> {
|
||||
// ensure we pass validation if the configuration has one
|
||||
if let Some(regex) = &self.0.open {
|
||||
if !regex.is_match(path) {
|
||||
return Err(Error::Validation {
|
||||
index: 0,
|
||||
validation: regex.as_str().into(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// The prevention of argument escaping is handled by the usage of std::process::Command::arg by
|
||||
// the `open` dependency. This behavior should be re-confirmed during upgrades of `open`.
|
||||
match with.map(Program::name) {
|
||||
Some(program) => ::open::with(path, program),
|
||||
None => ::open::that(path),
|
||||
}
|
||||
.map_err(Into::into)
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,4 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"include": ["guest-js/*.ts"]
|
||||
}
|
||||
Loading…
Reference in new issue