cargo-task-wasm 0.1.0

A task runner for Cargo
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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

<h1 align="center">cargo-task-wasm</h1>
<div align="center">
  <strong>
    A secure `cargo task` subcommand for Rust
  </strong>
</div>

<!-- <br />

<div align="center">
  <a href="https://crates.io/crates/cargo-task-wasm">
    <img src="https://img.shields.io/crates/v/cargo-task-wasm.svg?style=flat-square"
    alt="Crates.io version" />
  </a>
  <a href="https://crates.io/crates/cargo-task-wasm">
    <img src="https://img.shields.io/crates/d/cargo-task-wasm.svg?style=flat-square"
      alt="Download" />
  </a>
  <a href="https://docs.rs/cargo-task-wasm">
    <img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square"
      alt="docs.rs docs" />
  </a>
</div> -->

<div align="center">
  <h3>
    <a href="https://docs.rs/cargo-task-wasm">
      API Docs
    </a>
    <span> | </span>
    <a href="https://github.com/yoshuawuyts/cargo-task-wasm/releases">
      Releases
    </a>
    <span> | </span>
    <a href="https://github.com/yoshuawuyts/cargo-task-wasm/blob/master.github/CONTRIBUTING.md">
      Contributing
    </a>
  </h3>
</div>

## About

This project provides a new `cargo task` subcommand that can be used to run
project-local tasks inside a secure WebAssembly sandbox. It looks for files in a
`tasks/` subdirectory of your project's root, and compiles those to [Wasm
Components](https://component-model.bytecodealliance.org). This is an attempt at
formalizing [cargo-xtask](https://github.com/matklad/cargo-xtask) pattern into a
secure, first-class workflow.

## Installation

The `cargo task` subcommand compiles Rust to Wasm Components targeting [WASI
0.2](https://wasi.dev). In order to do that a working WASI 0.2 toolchain needs
to be present on the host system.

```sh
$ rustup +beta target add wasip2  # Install the WASI 0.2 target
$ cargo install cargo-task-wasm   # Install the `cargo task` subcommand
```

## Usage

```text
Usage: cargo task <TASK_NAME> [ARGS]...

Arguments:
  <TASK_NAME>  The name of the task to run
  [ARGS]...    Optional arguments to pass to the task

Options:
  -h, --help     Print help
  -V, --version  Print version
```

## Configuration

### Permissions

Tasks in `cargo task` follow the [principle of least
privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege). By
default they only get access to the working directory, and can access any
additional command line arguments passed to it. Additional permissions can be
configured via a `[tasks]` section in `Cargo.toml`.

```toml
[package]
name = "example"
version = "0.1.0"
edition = "2021"

[task-dependencies]
wstd = "0.4.0"

[tasks]
env = { permissions = { inherit-env = ["FOO"] } }   # inherit specific env vars
```

### Paths

By default the `cargo task` subcommand will look for commands in the `tasks/`
directory of the workspace. However, it is also able to find tasks located in
other locations by specifying custom paths.

```toml
[tasks]
print = { path = "tasks/print.rs" }   # define a custom path for the task
```

## Roadmap

- [x] Sketch out a repository layout or whatever workflow example
- [x] Create a new `cargo` subcommand
- [x] Hook up wasmtime to the subcommand
- [x] Add support for manual paths in a `[tasks]` section in `Cargo.toml`
- [x] Figure out how to configure capabilities for the tasks
- [ ] Add support for compiling cargo deps as part of subcommands
- [ ] Add support for installing tasks from crates.io

## See Also

- [Custom tasks in Cargo (Aaron Turon, 2016)](http://aturon.github.io/tech/2018/04/05/workflows/)
- [`matklad/cargo-xtask` (Alex Kladov, 2019)](https://github.com/matklad/cargo-xtask)

## Safety
This crate uses ``#![deny(unsafe_code)]`` to ensure everything is implemented in
100% Safe Rust.

## Contributing
Want to join us? Check out our ["Contributing" guide][contributing] and take a
look at some of these issues:

- [Issues labeled "good first issue"][good-first-issue]
- [Issues labeled "help wanted"][help-wanted]

[contributing]: https://github.com/yoshuawuyts/cargo-task-wasm/blob/master.github/CONTRIBUTING.md
[good-first-issue]: https://github.com/yoshuawuyts/cargo-task-wasm/labels/good%20first%20issue
[help-wanted]: https://github.com/yoshuawuyts/cargo-task-wasm/labels/help%20wanted

## License

<sup>
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
</sup>

<br/>

<sub>
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.
</sub>