weirdnet_plugin/abi.rs
1//! The Weirdnet plugin C ABI, version 2. Shared verbatim by hosts and plugins.
2//!
3//! Version 2 has the same layout and calling convention as version 1 of the SDK this one
4//! descends from; it differs in its symbol names and version number, so a host knows which
5//! SDK a library was built against and never mistakes one for the other.
6//!
7//! A plugin is a shared library (`.so`, `.dylib`, `.dll`) exporting three symbols:
8//!
9//! | symbol | signature | meaning |
10//! |--------|-----------|---------|
11//! | `weirdnet_plugin_abi` | `extern "C" fn() -> u32` | the ABI version it was built for ([`ABI_VERSION`]) |
12//! | `weirdnet_plugin_info` | `extern "C" fn() -> WnStr` | static UTF-8 JSON: `{"sdk": "0.1.0", "lang": "rust"}` (and `"kind"` from `plugin!(run, kind = "…")`) |
13//! | `weirdnet_plugin_run` | `unsafe extern "C" fn(*const WnHost) -> i32` | run once; [`RUN_OK`] or an error code |
14//!
15//! Everything else goes through the host table [`WnHost`]: `call(ctx, method, request, out)`
16//! takes a method name and a JSON request and fills `out` with a JSON reply that the plugin
17//! returns with `free`. Memory never crosses allocators: the host frees what it allocates,
18//! and the plugin only lends (`WnStr`) what it owns.
19//!
20//! Compatibility: the layout of these types and the three symbols never change within an
21//! ABI version. New host methods may be added at any time (`methods` lists them); a plugin
22//! asking for a method the host does not know gets an error, never a crash. A host refuses
23//! plugins whose `weirdnet_plugin_abi` is not one it supports.
24use core::ffi::c_void;
25
26/// The ABI version this file describes.
27pub const ABI_VERSION: u32 = 2;
28
29/// `weirdnet_plugin_run` finished; the result (or error) was handed to the host.
30pub const RUN_OK: i32 = 0;
31/// The run failed with an error (sent to the host with the `error` method).
32pub const RUN_ERROR: i32 = 1;
33/// The plugin panicked (the panic was caught; its message was sent with `error`).
34pub const RUN_PANIC: i32 = 2;
35
36/// `call` succeeded and `out` holds the JSON reply.
37pub const CALL_OK: i32 = 0;
38/// `call` failed and `out` holds the error message (UTF-8, not JSON).
39pub const CALL_ERROR: i32 = 1;
40
41/// Exported symbol names (NUL-terminated for `dlsym`).
42pub const SYM_ABI: &[u8] = b"weirdnet_plugin_abi\0";
43pub const SYM_INFO: &[u8] = b"weirdnet_plugin_info\0";
44pub const SYM_RUN: &[u8] = b"weirdnet_plugin_run\0";
45
46/// Borrowed UTF-8 bytes.
47#[repr(C)]
48#[derive(Clone, Copy)]
49pub struct WnStr {
50 pub ptr: *const u8,
51 pub len: usize,
52}
53
54impl WnStr {
55 pub fn new(s: &str) -> Self {
56 WnStr { ptr: s.as_ptr(), len: s.len() }
57 }
58 /// # Safety
59 /// `ptr` must point at `len` readable bytes for the lifetime `'a`.
60 pub unsafe fn as_bytes<'a>(&self) -> &'a [u8] {
61 if self.ptr.is_null() || self.len == 0 {
62 return &[];
63 }
64 unsafe { core::slice::from_raw_parts(self.ptr, self.len) }
65 }
66}
67
68/// Bytes owned by the host; give them back with [`WnHost::free`].
69#[repr(C)]
70pub struct WnBuf {
71 pub ptr: *mut u8,
72 pub len: usize,
73 pub cap: usize,
74}
75
76impl WnBuf {
77 pub const EMPTY: WnBuf = WnBuf { ptr: core::ptr::null_mut(), len: 0, cap: 0 };
78}
79
80/// Calls a host method: `method` name, `request` JSON; fills `out`; returns [`CALL_OK`] or [`CALL_ERROR`].
81pub type HostCall = unsafe extern "C" fn(ctx: *mut c_void, method: WnStr, request: WnStr, out: *mut WnBuf) -> i32;
82/// Frees a buffer the host filled.
83pub type HostFree = unsafe extern "C" fn(ctx: *mut c_void, buf: WnBuf);
84
85/// What the host gives a plugin for one run.
86#[repr(C)]
87pub struct WnHost {
88 pub abi_version: u32,
89 pub ctx: *mut c_void,
90 pub call: HostCall,
91 pub free: HostFree,
92}
93
94pub type PluginAbi = extern "C" fn() -> u32;
95pub type PluginInfo = extern "C" fn() -> WnStr;
96pub type PluginRun = unsafe extern "C" fn(host: *const WnHost) -> i32;