1# Zed's Plugin Runner
  2This is a short guide that aims to answer the following questions:
  3
  4- How do plugins work in Zed?
  5- How can I create a new plugin?
  6- How can I integrate plugins into a part of Zed?
  7
  8### Nomenclature
  9
 10- Host-side: The native Rust runtime managing plugins, e.g. Zed.
 11- Guest-side: The wasm-based runtime that plugins use.
 12
 13## How plugins work
 14Zed's plugins are WebAssembly (Wasm) based, and have access to the WebAssembly System Interface (WASI), which allows for permissions-based access to subsets of system resources, like the filesystem.
 15
 16To execute plugins, Zed's plugin system uses the sandboxed [`wasmtime`](https://wasmtime.dev/) runtime, which is Open Source and developed by the [Bytecode Alliance](https://bytecodealliance.org/). Wasmtime uses the [Cranelift](https://docs.rs/cranelift/latest/cranelift/) codegen library to compile plugins to native code.
 17
 18Zed has three `plugin` crates that implement different things:
 19
 201. `plugin_runtime` is a host-side library that loads and runs compiled `Wasm` plugins, in addition to setting up system bindings. This crate should be used host-side
 21
 222. `plugin` contains a prelude for guest-side plugins to depend on. It re-exports some required crates (e.g. `serde`, `bincode`) and provides some necessary macros for generating bindings that `plugin_runtime` can hook into.
 23
 243. `plugin_macros` implements the proc macros required by `plugin`, like the `#[import]` and `#[export]` attribute macros, and should also be used guest-side.
 25
 26### ABI
 27The interface between the host Rust runtime ('Runtime') and plugins implemented in Wasm ('Plugin') is pretty simple.
 28
 29When calling a guest-side function, all arguments are serialized to bytes and passed through `Buffer`s. We currently use `serde` + [`bincode`](https://docs.rs/bincode/latest/bincode/) to do this serialization. This means that any type that can be serialized using serde can be passed across the ABI boundary. For types that represent resources that cannot pass the ABI boundary (e.g. `Rope`), we are working on an opaque callback-based system.
 30
 31> **Note**: It's important to note that there is a draft ABI standard for Wasm called WebAssembly Interface Types (often abbreviated `WITX`). This standard is currently not stable and only experimentally supported in some runtimes. Once this proposal becomes stable, it would be a good idea to transition towards using WITX as the ABI, rather than the rather rudimentary `bincode` ABI we have now.
 32
 33All `Buffer`s are stored in Wasm linear memory (Wasm memory). A `Buffer` is a pointer, length pair to a byte array somewhere in Wasm memory. A `Buffer` itself is represented as a pair of two 4-byte (`u32`) fields:
 34
 35```rust
 36struct Buffer {
 37    ptr: u32,
 38    len: u32,
 39}
 40```
 41
 42Which we encode as a single `u64` when crossing the ABI boundary:
 43
 44```
 45+-------+-------+
 46| ptr   | len   |
 47+-------+-------+
 48        |
 49~ ~ ~ ~ | ~ ~ ~ ~ spOoky ABI boundary O.o
 50        V
 51+---------------+
 52| u64           |
 53+---------------+
 54```
 55
 56All functions that a plugin exports or imports have the following properties:
 57
 58- A function signature of `fn(u64) -> u64`, where both the argument (input) and return type (output) are a `Buffer`:
 59
 60    - The input `Buffer` will contain the input arguments serialized to `bincode`.
 61    - The output `Buffer` will contain the output arguments serialized to `bincode`.
 62
 63- Have a name starting with two underscores.
 64
 65Luckily for us, we don't have to worry about mangling names or writing serialization code. The `plugin::prelude::*` defines a couple of macros—aptly named `#[import]` and `#[export]`—that generate all serialization code and perform all mangling of names requisite for crossing the ABI boundary.
 66
 67There are also a couple important things every plugin must have:
 68
 69- `__alloc_buffer` function that, given a `u32` length, returns a `u32` pointer to a buffer of that length.
 70- `__free_buffer` function that, given a buffer encoded as a `u64`, frees the buffer at the given location, and does not return anything.
 71
 72Luckily enough for us yet again, the `plugin` prelude defines two ready-made versions of these functions, so you don't have to worry about implementing them yourselves.
 73
 74So, what does importing and exporting functions from a plugin look like in practice? I'm glad you asked...
 75
 76## Creating new plugins
 77Since Zed's plugin system uses Wasm + WASI, in theory any language that compiles to Wasm can be used to write plugins. In practice, and out of practicality, however, we currently only really support plugins written in Rust.
 78
 79A plugin is just a rust crate like any other. All plugins embedded in Zed are located in the `plugins` folder in the root. These plugins will automatically be compiled, optimized, and recompiled on change, so it's recommended that when creating a new plugin you create it there.
 80
 81As plugins are compiled to Wasm + WASI, you need to have the `wasm32-wasi` toolchain installed on your system. If you don't have it already, a little rustup magick will do the trick:
 82
 83```bash
 84rustup target add wasm32-wasi
 85```
 86
 87### Configuring a plugin
 88After you've created a new plugin in `plugins` using `cargo new --lib`, edit your `Cargo.toml` to ensure that it looks something like this:
 89
 90```toml
 91[package]
 92name = "my_very_cool_incredible_plugin_with_a_short_name_of_course"
 93version = "0.1.0"
 94edition = "2021"
 95
 96[lib]
 97crate-type = ["cdylib"]
 98
 99[dependencies]
100plugin = { path = "../../crates/plugin" }
101
102[profile.release]
103opt-level = "z"
104lto = true
105```
106
107Here's a quick explainer of what we're doing:
108
109- `crate-type = ["cdylib"]` is used because a plugin essentially acts a *library*, exposing functions with specific signatures that perform certain tasks. This key ensures that the library is generated in a reproducible manner with a layout `plugin_runtime` knows how to hook into.
110
111- `plugin = { path = "../../crates/plugin" }` is used so we have access to the prelude, which has a few useful functions and can automatically generate serialization glue code for us.
112
113- `[profile.release]` these options wholistically optimize for size, which will become increasingly important as we add more plugins.
114
115### Importing and Exporting functions
116To import or export a function, all you need are two things:
117
1181. Make sure that you've imported `plugin::prelude::*`
1192. Annotate your function or signature with `#[export]` or `#[import]` respectively.
120
121Here's an example plugin that doubles the value of every float in a `Vec<f64>` passed into it:
122
123```rust
124use plugin::prelude::*;
125
126#[export]
127pub fn double(mut x: Vec<f64>) -> Vec<f64> {
128    x.into_iter().map(|x| x * 2.0).collect()
129}
130```
131
132All the serialization code is automatically generated by `#[export]`.
133
134You can specify functions that must be defined host-side by using the `#[import]` attribute. This attribute must be attached to a function signature:
135
136```rust
137use plugin::prelude::*;
138
139#[import]
140fn run(command: String) -> Vec<u8>;
141```
142
143The `#[import]` macro will generate a function body that performs the proper serialization/deserialization needed to call out to the host rust runtime. Note that the same `serde` + `bincode` + `Buffer` ABI is used for both `#[import]` and `#[export]`.
144
145> **Note**: If you'd like to see an example of importing and exporting functions, check out the `test_plugin`, which can be found in the `plugins` directory.
146
147## Integrating plugins into Zed
148Currently, plugins are used to add support for language servers to Zed. Plugins should be fairly simple to integrate for library-like applications. Here's a quick overview of how plugins work:
149
150### Normal vs Precompiled plugins
151Plugins in the `plugins` directory are automatically recompiled and serialized to disk when compiling Zed. The resulting artifacts can be found in the `plugins/bin` directory. For each `plugin`, you should see two files:
152
153- `plugin.wasm` is the plugin compiled to Wasm. As a baseline, this should be about 4MB for debug builds and 2MB for release builds, but it depends on the specific plugin being built.
154
155- `plugin.wasm.pre` is the plugin compiled to Wasm *and additionally* precompiled to host-platform-agnostic cranelift-specific IR. This should be about 700KB for debug builds and 500KB in release builds. Each plugin takes about 1 or 2 seconds to compile to native code using cranelift, so precompiling plugins drastically reduces the startup time required to begin to run a plugin.
156
157> TODO: Rework precompiled plugins.
158
159For all intents and purposes, it is *highly recommended* that you use precompiled plugins where possible, as they are much more lightweight and take much less time to instantiate.
160
161### Instantiating a plugin
162So you have something you'd like to add a plugin for. What now? The general pattern for adding support for plugins is as follows:
163
164#### 1. Create a struct to hold the plugin
165To call the functions that a plugin exports host-side, you need to have 'handles' to those functions. Each handle is typed and stored in `WasiFn<A, R>` where `A: Serialize` and `R: DeserializeOwned`.
166
167For example, let's suppose we're creating a plugin that:
168
1691. formats a message 
1702. processes a list of numbers somehow
171
172We could create a struct for this plugin as follows:
173
174```rust
175use plugin_runtime::{WasiFn, Plugin};
176
177pub struct CoolPlugin {
178    format:  WasiFn<String, String>,
179    process: WasiFn<Vec<f64>, f64>,
180    runtime: Plugin,
181}
182```
183
184Note that this plugin also holds an owned reference to the runtime, which is stored in the `Plugin` type. In asynchronous or multithreaded contexts, it may be required to put `Plugin` behind an `Arc<Mutex<Plugin>>`. Although plugins expose an asynchronous interface, the underlying Wasm engine can only execute a single function at a time. 
185
186> **Note**: This is a limitation of the WebAssembly standard itself. In the future, to work around this, we've been considering starting a pool of plugins, or instantiating a new plugin per call (this isn't as bad as it sounds, as instantiating a new plugin only takes about 30µs).
187
188In the following steps, we're going to build a plugin and extract handles to fill this struct we've created.
189
190#### 2. Bind all imported functions
191While a plugin can export functions, it can also import them. We'll refer to the host-side functions that a plugin imports as 'native' functions. Native functions are represented using callbacks, and both synchronous and asynchronous callbacks are supported.
192
193To bind imported functions, the first thing we need to do is create a new plugin using `PluginBuilder`. `PluginBuilder` uses the builder pattern to configure a new plugin, after which calling the `init` method will instantiate the `Plugin`.
194
195You can create a new plugin builder as follows:
196
197```rust
198let builder = PluginBuilder::new_with_default_ctx();
199```
200
201This creates a plugin with a sensible default set of WASI permissions, namely the ability to write to `stdout` and `stderr` (note that, by default, plugins do not have access to `stdin`). For more control, you can use `PluginBuilder::new` and pass in a `WasiCtx` manually.
202
203##### Synchronous Functions
204To add a sync native function to a plugin, use the `.host_function` method:
205
206```rust
207let builder = builder.host_function(
208    "add_f64", 
209    |(a, b): (f64, f64)| a + b,
210).unwrap();
211```
212
213The `.host_function` method takes two arguments: the name of the function, and a sync callback that implements it. Note that this name must match the name of the function declared in the plugin exactly. For example, to use the `add_f64` from a plugin, you must include the following `#[import]` signature:
214
215```rust
216use plugin::prelude::*;
217
218#[import]
219fn add_f64(a: f64, b: f64) -> f64;
220```
221
222Note that the specific names of the arguments do not matter, as long as they are unique. Once a function has been imported, it may be used in the plugin as any other Rust function.
223
224##### Asynchronous Functions
225To add an async native function to a plugin, use the `.host_function_async` method:
226
227```rust
228let builder = builder.host_function_async(
229    "half", 
230    |n: f64| async move { n / 2.0 },
231).unwrap();
232```
233
234This method works exactly the same as the `.host_function` method, but requires a callback that returns an async future. On the plugin side, there is no distinction made between sync and async functions (as Wasm has no built-in notion of sync vs. async), so the required import signature should *not* use the `async` keyword:
235
236```rust
237use plugin::prelude::*;
238
239#[import]
240fn half(n: f64) -> f64;
241```
242
243All functions declared by the builder must be imported by the Wasm plugin, otherwise an error will be raised.
244
245#### 3. Get the compiled plugin
246Once all imports are marked, we can instantiate the plugin. To instantiate the plugin, simply call the `.init` method on a `PluginBuilder`:
247
248```rust
249let plugin = builder
250    .init(
251        true,
252        include_bytes!("../../../plugins/bin/cool_plugin.wasm.pre"),
253    )
254    .await
255    .unwrap();
256```
257
258The `.init` method currently takes two arguments:
259
2601. First, the 'precompiled' flag, indicating whether the plugin is *normal* (`.wasm`) or precompiled (`.wasm.pre`). When using a precompiled plugin, set this flag to `true`.
261
2622. Second, the raw plugin Wasm itself, as an array of bytes. When not precompiled, this can be either the Wasm binary format (`.wasm`) or the Wasm textual format (`.wat`). When precompiled, this must be the precompiled plugin (`.wasm.pre`).
263
264The `.init` method is asynchronous, and must be `.await`ed upon. If the plugin is malformed or doesn't import the right functions, an error will be raised.
265
266#### 4. Get handles to all exported functions
267Once the plugin has been compiled, it's time to start filling in the plugin struct defined earlier. In the case of `CoolPlugin` from earlier, this can be done as follows:
268
269```rust
270let mut cool_plugin = CoolPlugin {
271    format:  plugin.function("format").unwrap(),
272    process: plugin.function("process").unwrap(),
273    runtime: plugin,
274};
275```
276
277Because the struct definition defines the types of functions we're grabbing handles to, it's not required to specify the types of the functions here.
278
279Note that, yet again, the names of guest-side functions we import must match exactly. Here's an example of what that implementation might look like:
280
281```rust
282use plugin::prelude::*;
283
284#[export]
285pub fn format(message: String) -> String {
286    format!("Cool Plugin says... '{}!'", message)
287}
288
289#[export]
290pub fn process(numbers: Vec<f64>) -> f64 {
291    // Process by calculating the average
292    let mut total = 0.0;
293    for number in numbers.into_iter() {
294        total += number;
295    }
296    total / numbers.len()
297}
298```
299
300That's it! Now you have a struct that holds an instance of a plugin. The last thing you need to know is how to call out the plugin you've defined...
301
302### Using a plugin
303To call a plugin function, use the async `.call` method on `Plugin`:
304
305```rust
306let average = cool_plugin.runtime
307    .call(
308        &cool_plugin.process,
309        vec![1.0, 2.0, 3.0],
310    )
311    .await
312    .unwrap();
313```
314
315The `.call` method takes two arguments:
316
3171. A reference to the handle of the function we want to call.
3182. The input argument to this function.
319
320This method is async, and must be `.await`ed. If something goes wrong (e.g. the plugin panics, or there is a type mismatch between the plugin and `WasiFn`), then this method will return an error.
321
322## Last Notes
323This has been a brief overview of how the plugin system currently works in Zed. We hope to implement higher-level affordances as time goes on, to make writing plugins easier, and providing tooling so that users of Zed may also write plugins to extend their own editors.