Skip to main content

player_plugin_abi/
lib.rs

1//! Raw C-compatible contracts for Vesper Plugin Platform.
2//!
3//! Plugin authors should depend on `player-plugin`, not this crate. This crate
4//! intentionally exposes raw pointers and function tables for the generated
5//! native boundary and the checked host loader.
6
7#![warn(clippy::undocumented_unsafe_blocks)]
8
9use std::ffi::c_void;
10use std::mem::size_of;
11
12#[doc(hidden)]
13pub mod export;
14mod interfaces;
15
16pub use interfaces::*;
17
18/// NUL-terminated native entry symbol exported by every native plugin.
19pub const VESPER_PLUGIN_ENTRY_SYMBOL: &[u8] = b"vesper_plugin_entry\0";
20/// Human-readable native entry symbol without the terminating NUL byte.
21pub const VESPER_PLUGIN_ENTRY_SYMBOL_NAME: &str = "vesper_plugin_entry";
22
23/// Root ABI major implemented by this crate.
24pub const VESPER_PLUGIN_ABI_MAJOR: u16 = 1;
25/// Root ABI minor implemented by this crate.
26pub const VESPER_PLUGIN_ABI_MINOR: u16 = 0;
27
28/// Maximum UTF-8 byte length of a reverse-DNS plugin identity.
29pub const VESPER_MAX_PLUGIN_ID_BYTES: usize = 255;
30/// Maximum UTF-8 byte length of a human-readable plugin name.
31pub const VESPER_MAX_PLUGIN_NAME_BYTES: usize = 255;
32/// Maximum UTF-8 byte length of a capability instance identity.
33pub const VESPER_MAX_CAPABILITY_INSTANCE_ID_BYTES: usize = 255;
34/// Maximum number of interfaces exposed by one root.
35pub const VESPER_MAX_INTERFACES_PER_PLUGIN: u32 = 64;
36/// Maximum number of concurrently registered sessions per interface instance.
37pub const VESPER_MAX_SESSIONS_PER_INTERFACE: usize = 1_024;
38/// Maximum number of concurrently retained leases in one session.
39pub const VESPER_MAX_LEASES_PER_SESSION: usize = 64;
40/// Maximum size accepted for one plugin-owned ABI allocation.
41pub const VESPER_MAX_OWNED_BYTES: u64 = 16 * 1024 * 1024;
42/// Maximum size accepted for one borrowed source-normalizer packet payload.
43pub const VESPER_MAX_PACKET_BYTES: u64 = 16 * 1024 * 1024;
44/// Maximum size accepted for one borrowed PCM frame payload.
45pub const VESPER_MAX_PCM_BYTES: u64 = 16 * 1024 * 1024;
46
47/// Raw status returned across the native ABI.
48///
49/// Callers must preserve unknown values so a newer plugin cannot be mistaken
50/// for a successful older plugin.
51pub type VesperStatus = u32;
52
53/// Stable plugin status values.
54pub mod status {
55    use super::VesperStatus;
56
57    pub const OK: VesperStatus = 0;
58    pub const FAILURE: VesperStatus = 1;
59    pub const INVALID_ARGUMENT: VesperStatus = 2;
60    pub const INCOMPATIBLE: VesperStatus = 3;
61    pub const STALE_HANDLE: VesperStatus = 4;
62    pub const POISONED: VesperStatus = 5;
63    pub const UNSUPPORTED: VesperStatus = 6;
64    pub const CANCELLED: VesperStatus = 7;
65    pub const TIMEOUT: VesperStatus = 8;
66    pub const ABI_VIOLATION: VesperStatus = 9;
67    pub const NOT_FOUND: VesperStatus = 10;
68    pub const AMBIGUOUS: VesperStatus = 11;
69    pub const EXHAUSTED: VesperStatus = 12;
70    pub const PANIC: VesperStatus = 13;
71}
72
73/// Canonical UUID bytes identifying a typed plugin interface.
74///
75/// Bytes use RFC 4122 network order. Consumers must not reinterpret them as a
76/// native-endian `u128`.
77#[repr(transparent)]
78#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
79pub struct VesperInterfaceId(pub [u8; 16]);
80
81pub const POST_DOWNLOAD_PROCESSOR_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
82    0xe9, 0x47, 0x9d, 0xbc, 0x42, 0xd2, 0x57, 0x5e, 0xb3, 0x9e, 0xa2, 0x4b, 0xc5, 0x12, 0xfb, 0xc7,
83]);
84pub const PIPELINE_EVENT_HOOK_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
85    0xc7, 0xa6, 0x94, 0x75, 0x79, 0xb2, 0x5b, 0x5e, 0xa4, 0x77, 0x08, 0x84, 0x4a, 0x5d, 0xa5, 0xd1,
86]);
87pub const BENCHMARK_SINK_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
88    0x2d, 0x8e, 0x5b, 0xe8, 0xb1, 0xde, 0x5e, 0x83, 0x8f, 0xe0, 0x61, 0x18, 0xaa, 0xbc, 0x51, 0x18,
89]);
90pub const NATIVE_DECODER_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
91    0xd6, 0x8b, 0xe0, 0xed, 0x19, 0x58, 0x59, 0x22, 0x8b, 0x7a, 0xbc, 0x67, 0x78, 0xa2, 0x6b, 0x43,
92]);
93pub const FRAME_PROCESSOR_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
94    0xfc, 0x05, 0x05, 0x97, 0xb7, 0xb7, 0x5c, 0x81, 0x83, 0xb9, 0xb4, 0x25, 0x55, 0xf8, 0xb8, 0x25,
95]);
96pub const AUDIO_PROCESSOR_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
97    0xf3, 0xfc, 0x5d, 0x7c, 0x58, 0x1f, 0x5e, 0x0a, 0x85, 0xbf, 0xdf, 0x00, 0xd7, 0xad, 0xb1, 0x3e,
98]);
99pub const SOURCE_NORMALIZER_PACKET_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
100    0xa2, 0xd6, 0x53, 0xfa, 0xd6, 0xce, 0x5f, 0x14, 0x93, 0xb8, 0xa8, 0x18, 0xa7, 0xa7, 0x7f, 0xdf,
101]);
102pub const SOURCE_NORMALIZER_RESOURCE_INTERFACE_ID: VesperInterfaceId = VesperInterfaceId([
103    0xb7, 0x6d, 0x1f, 0x06, 0x62, 0xd7, 0x5d, 0x71, 0xaa, 0x06, 0x27, 0x80, 0xe4, 0xb4, 0xfd, 0x0d,
104]);
105
106/// Host-owned bytes borrowed for one synchronous ABI call.
107#[repr(C)]
108#[derive(Debug, Clone, Copy, PartialEq, Eq)]
109pub struct VesperByteSlice {
110    pub data: *const u8,
111    pub len: u64,
112}
113
114impl VesperByteSlice {
115    pub const fn empty() -> Self {
116        Self {
117            data: std::ptr::null(),
118            len: 0,
119        }
120    }
121}
122
123impl Default for VesperByteSlice {
124    fn default() -> Self {
125        Self::empty()
126    }
127}
128
129/// Plugin-owned bytes released through `VesperPluginRoot::free_bytes`.
130#[repr(C)]
131#[derive(Debug, Clone, Copy, PartialEq, Eq)]
132pub struct VesperOwnedBytes {
133    pub data: *mut u8,
134    pub len: u64,
135}
136
137impl VesperOwnedBytes {
138    pub const fn empty() -> Self {
139        Self {
140            data: std::ptr::null_mut(),
141            len: 0,
142        }
143    }
144
145    #[doc(hidden)]
146    pub fn from_vec(bytes: Vec<u8>) -> Self {
147        if bytes.is_empty() {
148            return Self::empty();
149        }
150        let mut bytes = bytes.into_boxed_slice();
151        let result = Self {
152            data: bytes.as_mut_ptr(),
153            len: bytes.len() as u64,
154        };
155        std::mem::forget(bytes);
156        result
157    }
158
159    /// Reclaims bytes allocated by [`Self::from_vec`].
160    ///
161    /// # Safety
162    ///
163    /// The value must have been returned by `from_vec` in the current dynamic
164    /// library and must not have been reclaimed previously.
165    #[doc(hidden)]
166    pub unsafe fn into_vec(self) -> Vec<u8> {
167        if self.data.is_null() || self.len == 0 {
168            return Vec::new();
169        }
170        let Ok(len) = usize::try_from(self.len) else {
171            return Vec::new();
172        };
173        // SAFETY: guaranteed by the caller contract. `from_vec` transfers a
174        // boxed slice with exactly this length.
175        unsafe { Box::from_raw(std::ptr::slice_from_raw_parts_mut(self.data, len)).into_vec() }
176    }
177}
178
179impl Default for VesperOwnedBytes {
180    fn default() -> Self {
181        Self::empty()
182    }
183}
184
185/// Header prefix shared by every typed interface table.
186#[repr(C)]
187#[derive(Debug, Clone, Copy)]
188pub struct VesperInterfaceHeader {
189    pub struct_size: u32,
190    pub interface_id: VesperInterfaceId,
191    pub major: u16,
192    pub minor: u16,
193    pub context: *mut c_void,
194}
195
196impl VesperInterfaceHeader {
197    pub const fn new(
198        struct_size: u32,
199        interface_id: VesperInterfaceId,
200        major: u16,
201        minor: u16,
202        context: *mut c_void,
203    ) -> Self {
204        Self {
205            struct_size,
206            interface_id,
207            major,
208            minor,
209            context,
210        }
211    }
212}
213
214/// Host-initialized result for root interface enumeration.
215#[repr(C)]
216#[derive(Debug, Clone, Copy)]
217pub struct VesperInterfaceDescriptor {
218    pub struct_size: u32,
219    pub interface_id: VesperInterfaceId,
220    pub major: u16,
221    pub minor: u16,
222    /// Borrowed reverse-DNS capability instance identity.
223    pub instance_id: VesperByteSlice,
224}
225
226impl Default for VesperInterfaceDescriptor {
227    fn default() -> Self {
228        Self {
229            struct_size: abi_size::<Self>(),
230            interface_id: VesperInterfaceId([0; 16]),
231            major: 0,
232            minor: 0,
233            instance_id: VesperByteSlice::empty(),
234        }
235    }
236}
237
238/// Stable native root returned by `vesper_plugin_entry`.
239#[repr(C)]
240#[derive(Debug, Clone, Copy)]
241pub struct VesperPluginRoot {
242    pub struct_size: u32,
243    pub abi_major: u16,
244    pub abi_minor: u16,
245    /// Unique owner for all interfaces and plugin-owned byte allocations.
246    pub owner: *mut c_void,
247    /// Borrowed validated reverse-DNS plugin identity.
248    pub plugin_id: VesperByteSlice,
249    /// Borrowed human-readable plugin name.
250    pub plugin_name: VesperByteSlice,
251    pub interface_count: u32,
252    pub reserved: u32,
253    pub interface_at: Option<
254        unsafe extern "C" fn(
255            owner: *mut c_void,
256            index: u32,
257            out_descriptor: *mut VesperInterfaceDescriptor,
258        ) -> VesperStatus,
259    >,
260    pub query_interface: Option<
261        unsafe extern "C" fn(
262            owner: *mut c_void,
263            interface_id: *const VesperInterfaceId,
264            instance_id: VesperByteSlice,
265            requested_major: u16,
266            minimum_minor: u16,
267            out_interface: *mut *const VesperInterfaceHeader,
268        ) -> VesperStatus,
269    >,
270    pub free_bytes: Option<unsafe extern "C" fn(owner: *mut c_void, bytes: VesperOwnedBytes)>,
271    pub destroy_owner: Option<unsafe extern "C" fn(owner: *mut c_void)>,
272}
273
274/// Native plugin entry point signature.
275pub type VesperPluginEntryPoint = unsafe extern "C" fn() -> *const VesperPluginRoot;
276
277/// Returns the ABI size field for a concrete `repr(C)` type.
278pub const fn abi_size<T>() -> u32 {
279    size_of::<T>() as u32
280}
281
282#[cfg(test)]
283mod tests {
284    use std::mem::{align_of, offset_of, size_of};
285
286    use super::*;
287
288    #[test]
289    fn interface_ids_use_canonical_uuid_bytes() {
290        assert_eq!(
291            POST_DOWNLOAD_PROCESSOR_INTERFACE_ID.0,
292            [
293                0xe9, 0x47, 0x9d, 0xbc, 0x42, 0xd2, 0x57, 0x5e, 0xb3, 0x9e, 0xa2, 0x4b, 0xc5, 0x12,
294                0xfb, 0xc7,
295            ]
296        );
297        assert_eq!(SOURCE_NORMALIZER_RESOURCE_INTERFACE_ID.0[0], 0xb7);
298        assert_eq!(SOURCE_NORMALIZER_RESOURCE_INTERFACE_ID.0[15], 0x0d);
299        assert_eq!(
300            AUDIO_PROCESSOR_INTERFACE_ID.0,
301            [
302                0xf3, 0xfc, 0x5d, 0x7c, 0x58, 0x1f, 0x5e, 0x0a, 0x85, 0xbf, 0xdf, 0x00, 0xd7, 0xad,
303                0xb1, 0x3e,
304            ]
305        );
306    }
307
308    #[test]
309    fn interface_header_is_a_stable_table_prefix() {
310        assert_eq!(offset_of!(VesperInterfaceHeader, struct_size), 0);
311        assert_eq!(offset_of!(VesperInterfaceHeader, interface_id), 4);
312        assert_eq!(offset_of!(VesperInterfaceHeader, major), 20);
313        assert_eq!(offset_of!(VesperInterfaceHeader, minor), 22);
314        assert!(offset_of!(VesperInterfaceHeader, context) >= 24);
315        assert_eq!(
316            align_of::<VesperInterfaceHeader>(),
317            align_of::<*mut c_void>()
318        );
319    }
320
321    #[test]
322    fn host_initialized_descriptor_advertises_its_capacity() {
323        let descriptor = VesperInterfaceDescriptor::default();
324        assert_eq!(
325            descriptor.struct_size as usize,
326            size_of::<VesperInterfaceDescriptor>()
327        );
328        assert_eq!(descriptor.interface_id, VesperInterfaceId([0; 16]));
329        assert_eq!(descriptor.instance_id, VesperByteSlice::empty());
330    }
331
332    #[test]
333    fn raw_status_keeps_unknown_values() {
334        let unknown: VesperStatus = u32::MAX;
335        assert_ne!(unknown, status::OK);
336        assert_ne!(unknown, status::FAILURE);
337    }
338
339    #[test]
340    fn root_places_size_and_version_before_pointer_fields() {
341        assert_eq!(offset_of!(VesperPluginRoot, struct_size), 0);
342        assert_eq!(offset_of!(VesperPluginRoot, abi_major), 4);
343        assert_eq!(offset_of!(VesperPluginRoot, abi_minor), 6);
344        assert_eq!(offset_of!(VesperPluginRoot, owner), 8);
345        assert!(size_of::<VesperPluginRoot>() >= size_of::<VesperInterfaceHeader>());
346    }
347}