Add `plugin.call_with_host_context` and `current_plugin.host_context`
methods, enabling per-call context to be looped from the guest invocation
to any host functions it calls. In an HTTP server environment, this enables
re-using a plugin across multiple requests while switching out backing
connections and user information in host functions. (Imagine a host
function, `update_user` -- previously the plugin would have to have been
aware of the user to pass to the host function. Now that information is
ambient.)
This is a backwards-compatible change and requires no changes to
existing plugins.
Implement by adding a global, mutable externref to the extism kernel.
Since most programming languages, including Rust, don't let you define
these natively, we accomplish this by using `wasm-merge` to combine the
kernel Wasm with Wasm generated by a WAT file containing only the
global.
(This pattern might be useful for other Wasm constructs we can't use
directly from Rust, like `v128` in argument parameters.)
Wasmtime requires extern refs to be `Any + Send + Sync + 'static`; we
additionally add `Clone`. I haven't tried this with an `Arc` directly,
but it should work at least for container structs that hold `Arc`'s
themselves.
Okay, phew.
The main bug from the [last
PR](https://github.com/extism/extism/pull/610) was that the rust
releases scramble to publish, but we have to publish them in a
particular order for the release to work since they depend on each
other.
There's a secondary bug: `cargo publish` is prone to 502'ing on publish.
I lean towards seeing how painful this is in practice; we should be able
to safely re-run the release flow on failure.
Follow-up to f7d297f98f.
Update the release workflows for the dependent crates. The Cargo
workflows run on GitHub release publish to match the Python package
release workflow. This means all of our crates are versioned in lockstep
by the Git tag.
There are four changes:
1. Trigger the workflows on GitHub release publish
2. Add the `set version` step from `release.yml` to modify the version
tags in `Cargo.toml`.
3. Publish with `--allow-dirty` (to account for the edit in step 2)
4. In `extism-maturin`, do not inherit `authors` from the workspace
since [PyPI rejects the value we have
set](https://github.com/extism/extism/actions/runs/7012534645/job/19077216730#step:7:23).
The `x86_64-unknown-linux-musl` target does not build dynamic libraries
for now:
```
warning: dropping unsupported crate type `cdylib` for target `x86_64-unknown-linux-musl`
```
A target may now be optionally specified to the root `Makefile`,
example:
`make RUST_TARGET=x86_64-unknown-linux-musl && sudo make
RUST_TARGET=x86_64-unknown-linux-musl install`
The new musl targets may be used to create entirely static binaries with
libextism. See the new `musl-static` target in `libextism/Makefile`
Adds `pkg-config` configs for dynamic and static builds of libextism.
Example usage is shown in `libextism/Makefile`.
Added the `.in` versions of the `.pc` files to non-MSVC releases.
See #504
Removes CI for the in-repo SDKs, we can remove the actual code closer to
the 1.0 release.
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: zshipko <zshipko@users.noreply.github.com>
* libextism is now built to crate-type `staticlib` as recommend by
@zshipko
* updated `Makefile` to install and uninstall the static library.
* updated c example to have `static` target to link libextism statically
* Compiler is no longer hardcoded to `clang`. Set `CC` to use a compiler
other than the system compiler. Tested with `gcc` and `clang`.
* added `static-artifact` to actions release. Untested as it's only ran
on push with tag.
---------
Co-authored-by: zach <zach@dylibso.com>
NuGet supports the distribution of native binaries. We already provide a
win-x64 package, this PR adds packages for the other environments. We
will be publishing these NuGet packages:
- Extism.runtime.linux-arm64
- Extism.runtime.linux-musl-arm64
- Extism.runtime.linux-x64
- Extism.runtime.osx-arm64
- Extism.runtime.osx-x64
- Extism.runtime.win-x64 (msvc)
- Extism.runtime.all -> this is a meta package that referencs all other
packages. The idea is, in the getting started guides we instruct the
user to take a dependency on `Extism.Sdk` and `Extism.runtime.all`. This
will make sure their apps work on all supported operating systems
automatically. Otherwise, they can just take a dependency on what they
care about
This PR also adds a dependency on
[MinVer](https://github.com/adamralph/minver) which make sure packages
are automatically versioned based on git tags.
Related to #486
This workflow only _uploads_ existing artifacts, so keeping a poetry
cache around just, uh, breaks the workflow since there's no `Poetry.lock`
to cache.
- Adds benchmarking, run with `cargo bench` or `cargo criterion`
- Adds `MemoryRoot::pointer_in_bounds_fast` to do less precise bounds
checking in loads/stores
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: zshipko <zshipko@users.noreply.github.com>
Maturin on Windows struggles with GNU headers. Since we have windows
MSVC wheel builds, this commit disables windows GNU wheel builds.
Also: fix a bug where the produced wheels did not include any extism
functions.
Build the python native library along with libextism since they change
at roughly the same rate; we can pull the resulting wheels into
python-sdk as needed.
Reduce the release job into a single matrix of `OS x RUST TARGET` – this
unifies the macos, windows, and linux builds into a single job.
---
**BREAKING CHANGE**: This changes the trigger for the release workflow.
Instead of being triggered by the creation of a release, it is triggered
by pushing new git tags. It will catch `v*` – `v0.5.0`, `v200.0.1-dev`
for example. The workflow creates a draft release.
Same as #471 for `main` branch
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: zshipko <zshipko@users.noreply.github.com>
Closes#469
This PR adds a github workflow that is triggered by updates to the
`kernel/` directory or `runtime/src/extism-kernel.wasm` - it builds the
kernel, including using `wasm-strip` and makes a PR against any PR that
has a kernel module that doesn't match the expected output.
I had considered making this run when the PR is merged into main, but
this approach gives us a chance to run CI with the generated wasm file.
I think automatically adding a commit would be simpler, but this way
seems more transparent.
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: zshipko <zshipko@users.noreply.github.com>
Add a "latest" snapshot that other libraries can use to test against the
latest version of Extism.
Add caching for builds triggered by pushes to `main`.
- Adds `extism-convert` crate with `ToBytes`, `FromBytes` and
`FromBytesOwned` traits
- This serves as a single interface for reading/writing rich types from
WebAssembly linear memory.
- Supports `Json` and `Msgpack` and `Protobuf` encodings out-of-the-box
- Updates `Plugin::call` to take `ToBytes` as the input argument and
return a `FromBytes` value
- Adds `host_fn!` macro to simplify host function creation
- Cleans up generated documentation a little
- PR for the Rust PDK: https://github.com/extism/rust-pdk/pull/31
- Adds a `typed_plugin!` macro to implement type-safe wrappers around
`Plugin`
- After this we should focus on adding similar type-conversion helpers
to the SDKs and other PDKs to make it easier to use across languages.
For example, a Python host running a Rust plugin using Msgpack encoded
types.
## Examples
### Calling a function
Instead of the untyped, bytes-only `call` function:
```rust
let output = plugin.call("func_name", "my data").unwrap();
let output: MyType = serde_json::from_slice(&output).unwrap();
```
We can now use richer types to encode/decode our values directly when
using `call`:
```rust
let Json(output) = plugin.call::<_, Json<MyType>>("func_name", "my data").unwrap();
```
### Allocating inside of a host function
The same interface works for host functions, so instead of:
```rust
fn hello_world(
plugin: &mut CurrentPlugin,
inputs: &[Val],
outputs: &mut [Val],
_user_data: UserData,
) -> Result<(), Error> {
let handle = plugin.memory_handle_val(&inputs[0])?;
let input = plugin.memory_read_str(handle)?;
let output = plugin.memory_alloc_bytes(&input).unwrap();
outputs[0] = output.into();
Ok(())
}
```
Becomes:
```rust
fn hello_world(
plugin: &mut CurrentPlugin,
inputs: &[Val],
outputs: &mut [Val],
_user_data: UserData,
) -> Result<(), Error> {
let my_value: String = plugin.memory_get_val(&inputs[0])?;
let output = plugin.memory_new(&my_value)?;
outputs[0] = plugin.memory_to_val(output);
Ok(())
}
```
Although this isn't much of an improvement, using the `host_fn` macro,
we can really begin to see how the above function is really just an
identity function:
```rust
host_fn!(hello_world(a: String) -> String {
a
});
```
### typed_plugin!
`typed_plugin!` is used to make a typed wrapper around a Plugin:
```rust
/// Create the typed plugin
typed_plugin!(Testing {
count_vowels(&str) -> Json<Count>
});
/// Create the `Plugin` and convert it to `Testing` wrapper
let mut plugin: Testing = Plugin::new(WASM, [f], true).unwrap().into();
/// Call the `count_vowels` function:
let Json(output0): Json<Count> = plugin.count_vowels("abc123")?;
```
It could make sense to convert `host_fn` and/or `typed_plugin` to
proc-macros at some point, but for now they work and provide some
flexibility in experimenting with the interfaces. Another future update
could be to figure out a nice way to make it so input can be written in
multiple chunks, so the entire input doesn't have to get copied into
memory at once.
- Removes the `ExtismContext` type from runtime and all SDKs
- Removed SDK functions: `extism_context_new`, `extism_context_reset`,
`extism_context_free`
- All SDKs have been updated, but there are still some TODOs below
- Removes `extism_plugin_update`
- Plugins can no longer be updated - a new plugin should be created
instead
- Adds `extism_plugin_id` to uniquely identify plugins
- Merges the `extism-runtime` and `extism` crates (there is no longer an
`extism-runtime` crate)
- Makes `extism::Manifest` an alias for `extism_manifest::Manifest`
instead of a distinct type
- Adds `MemoryHandle` type to SDKs to refer to blocks of Extism memory
that can be accessed in host functions
- Improves thread-safety of Plugins, adds C++ test to call a single
plugin from multiple threads.
- Expands wasmtime bounds to include 12.0
EIP: https://github.com/extism/proposals/pull/8
This PR makes minor breaking changes to several SDKs, but not to runtime
C API. The threadsafety updates in the Rust SDK are kind of specific to
Rust, I'm not sure if it makes sense to add the locks to all the other
SDKs at this point. For the most part the `Context` and `Plugin` types
in the SDKs should be safe to use protected by a mutex but they aren't
inherently threadsafe. That kind of locking should probably be done by
the user.
- Runtime
- improve thread safety
- reinstantiates less
- fixes a potential resource exhaustion bug from re-instantiating using
the same store too many times
- Rust SDK
- adds `Send` and `Sync` implementations for `Context`
- adds test sharing a context between threads
- adds `Plugin::call_map` to call a plugin and handle the output with
the lock held
- adds testing sharing an `Arc<Mutex<Plugin>>` between threads
- adds `Plugin::create` and `Plugin::create_from_manifest` to create a
plugin without a `Context`
- Python
- BREAKING
- changes `Plugin` constructor to take `context` as an optional named
argument, to update use `Plugin(data, context=context)` instead
- Ruby
- BREAKING
- changes `Plugin` constructor to take `context` as an optional named
argument, to update use `Plugin.new(data, context=context)` instead
- Go
- adds `NewPlugin` and `NewPluginFromManifest` functions
- Node
- BREAKING
- changes `Plugin` constructor to take `context` as an optional named
argument, to update use `new Plugin(data, wasi, config, host, context)`
instead of `new Plugin(context, data, wasi, functions, config)` (most
people are probably using `context.plugin` instead of the Plugin
constructor anyway)
- OCaml
- BREAKING
- changes `Plugin.create` and `Plugin.of_manifest` to take `context` as
an optional named argument, to update `Plugin.create ~context data` and
`Plugin.of_manifest ~context data` instead
- Haskell
- adds `createPlugin` and `createPluginFromManifest` functions
- Elixir
- adds `Plugin.new` to make a plugin without going through
`Context.new_plugin`
- Java
- adds new `Plugin` constructors without a `Context` argument
- C++
- BREAKING
- Updates `Plugin` constructor to take an optional context as the last
argument, instead of requiring it to be the first argument
- Use `Plugin(wasm, wasi, functions, ctx)` instead of `Plugin(ctx, wasm,
wasi, functions)`
- Zig
- Adds `Plugin.create` and `Plugin.createWithManifest` to create plugins
in their own context.
---------
Co-authored-by: zach <zach@dylib.so>
Co-authored-by: Benjamin Eckel <bhelx@simst.im>
There are some breaking changes:
- Plugin.init now requires an allocator and functions slice
- Plugin.initFromManifest now requires a functions slice
- Plugin struct removed in favor of using the file as struct
- from @nilslice: https://zig.news/gowind/zig-files-are-structs-288j
(good reference!)
---------
Co-authored-by: Steve Manuel <steve@dylib.so>
Can't quite figure out what is going on. Jest cannot resolves our code
fine but can't seem to resolve the NPM module:
```
FAIL src/index.test.ts
● Test suite failed to run
Cannot find module '@bjorn3/browser_wasi_shim' from 'src/plugin.ts'
Require stack:
src/plugin.ts
src/context.ts
src/index.ts
src/index.test.ts
2 | import { PluginConfig } from './manifest';
3 | //@ts-ignore TODO add types to this library
> 4 | import { WASI, File } from "@bjorn3/browser_wasi_shim";
| ^
5 |
6 | export default class ExtismPlugin {
7 | moduleData: ArrayBuffer;
at Resolver._throwModNotFoundError (node_modules/jest-resolve/build/resolver.js:425:11)
at Object.<anonymous> (src/plugin.ts:4:1)
at Object.<anonymous> (src/context.ts:2:1)
at Object.<anonymous> (src/index.ts:1:1)
at Object.<anonymous> (src/index.test.ts:1:1)
Test Suites: 1 failed, 1 total
Tests: 0 total
Snapshots: 0 total
Time: 0.916 s
Ran all test suites.
```
For now let's comment it out since it's not providing value anyway.
Hi,
We want to use Extism on our project
[Otoroshi](https://github.com/MAIF/otoroshi) but we need to run it on
jdk11
This pull request makes everything run smoothly on jdk11
If you have any suggestion about this pull request, i'm open to it
Thanks for your time
Takes new version of the wasi shim and ensures that both CJS and ESM
distributions can be built.
Already published as 0.2.2
Co-authored-by: Steve Manuel <steve@dylib.so>
