Skip to main content

player_plugin_wasm/
lib.rs

1#![no_std]
2#![warn(clippy::undocumented_unsafe_blocks)]
3
4//! Safe guest runtime support for Vesper WASM Component plugins.
5//!
6//! Plugin authors use [`generate`] for WIT bindings and
7//! [`export_component!`] for the final Component export. The crate owns the
8//! allocator, panic, and canonical ABI reallocation boundary required by
9//! `wasm32-wasip2`, so author crates can deny unsafe code.
10
11extern crate alloc;
12
13pub use wit_bindgen::generate;
14
15#[cfg(all(
16    target_arch = "wasm32",
17    target_os = "wasi",
18    target_env = "p2",
19    target_feature = "atomics"
20))]
21compile_error!("Vesper WASM plugins do not support the wasm atomics target feature");
22
23#[cfg(all(target_arch = "wasm32", target_os = "wasi", target_env = "p2"))]
24#[global_allocator]
25static ALLOCATOR: dlmalloc::GlobalDlmalloc = dlmalloc::GlobalDlmalloc;
26
27#[cfg(all(target_arch = "wasm32", target_os = "wasi", target_env = "p2"))]
28#[panic_handler]
29fn panic(_info: &core::panic::PanicInfo<'_>) -> ! {
30    core::arch::wasm32::unreachable()
31}
32
33#[cfg(all(target_arch = "wasm32", target_os = "wasi", target_env = "p2"))]
34#[unsafe(export_name = "cabi_realloc")]
35unsafe extern "C" fn canonical_abi_realloc(
36    old_ptr: *mut u8,
37    old_len: usize,
38    align: usize,
39    new_len: usize,
40) -> *mut u8 {
41    use alloc::alloc::{Layout, alloc, handle_alloc_error, realloc};
42
43    if old_len == 0 {
44        if new_len == 0 {
45            return align as *mut u8;
46        }
47        let Ok(layout) = Layout::from_size_align(new_len, align) else {
48            core::arch::wasm32::unreachable();
49        };
50        // SAFETY: `layout` was validated above and the returned allocation is
51        // owned by the canonical ABI caller until it is passed back here.
52        let pointer = unsafe { alloc(layout) };
53        if pointer.is_null() {
54            handle_alloc_error(layout);
55        }
56        return pointer;
57    }
58
59    if old_ptr.is_null() || new_len == 0 {
60        core::arch::wasm32::unreachable();
61    }
62    let Ok(old_layout) = Layout::from_size_align(old_len, align) else {
63        core::arch::wasm32::unreachable();
64    };
65    let Ok(new_layout) = Layout::from_size_align(new_len, align) else {
66        core::arch::wasm32::unreachable();
67    };
68    // SAFETY: the Component canonical ABI only returns pointers allocated by
69    // this function, and `old_layout` preserves the original size/alignment.
70    let pointer = unsafe { realloc(old_ptr, old_layout, new_len) };
71    if pointer.is_null() {
72        handle_alloc_error(new_layout);
73    }
74    pointer
75}
76
77#[doc(hidden)]
78pub mod rt {
79    pub use wit_bindgen::rt::*;
80
81    pub fn maybe_link_cabi_realloc() {
82        #[cfg(all(target_arch = "wasm32", target_os = "wasi", target_env = "p2"))]
83        {
84            let realloc = super::canonical_abi_realloc
85                as unsafe extern "C" fn(*mut u8, usize, usize, usize) -> *mut u8;
86            core::hint::black_box(realloc);
87        }
88        #[cfg(not(all(target_arch = "wasm32", target_os = "wasi", target_env = "p2")))]
89        wit_bindgen::rt::maybe_link_cabi_realloc();
90    }
91}
92
93/// Exports a generated Vesper Component while linking the bounded guest
94/// runtime required by `wasm32-wasip2`.
95///
96/// The first argument is the module produced by [`generate`]. The second is
97/// the type implementing the generated guest traits.
98#[macro_export]
99macro_rules! export_component {
100    ($bindings:ident, $component:ident) => {
101        #[cfg(not(all(target_arch = "wasm32", target_os = "wasi", target_env = "p2")))]
102        compile_error!("Vesper WASM plugins must target wasm32-wasip2");
103
104        #[allow(unsafe_code)]
105        mod __vesper_generated_component_export {
106            use super::{$bindings, $component};
107
108            $bindings::export!($component with_types_in $bindings);
109        }
110    };
111}