audio-plugin-bsd 0.1.1

Dynamic .so audio-plugin loader with ABI verification and FreeBSD Capsicum/pdfork per-process sandboxing for real-time audio in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

//! Static metadata describing a loaded plugin (name, version, description, ...).

/// Human-readable metadata for an audio plugin.
///
/// A plugin exposes this — via an `extern "C"` accessor in the full loader —
/// so the host can log plugin identity without interpreting plugin internals.
/// The `abi_version` field records which host ABI the plugin was built
/// against (see [`crate::abi`]).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PluginMetadata {
    /// Short human-readable name of the plugin (e.g. `"reverb-plate"`).
    pub name: String,
    /// Plugin version string (typically semver, e.g. `"0.3.1"`); free-form.
    pub version: String,
    /// One-line description of what the plugin does.
    pub description: String,
    /// Optional author / vendor string.
    pub author: Option<String>,
    /// Encoded ABI version this plugin was built against (see [`crate::abi`]).
    pub abi_version: u32,
    /// Optional SPDX licence identifier (e.g. `"MIT"`).
    pub license: Option<String>,
}

impl PluginMetadata {
    /// Construct a [`PluginMetadata`] with the required fields, leaving
    /// `author` and `license` as `None`.
    #[must_use]
    pub fn new(
        name: impl Into<String>,
        version: impl Into<String>,
        description: impl Into<String>,
        abi_version: u32,
    ) -> Self {
        Self {
            name: name.into(),
            version: version.into(),
            description: description.into(),
            author: None,
            abi_version,
            license: None,
        }
    }

    /// Builder: set the `author` field.
    #[must_use]
    pub fn with_author(mut self, author: impl Into<String>) -> Self {
        self.author = Some(author.into());
        self
    }

    /// Builder: set the `license` field.
    #[must_use]
    pub fn with_license(mut self, license: impl Into<String>) -> Self {
        self.license = Some(license.into());
        self
    }
}

#[cfg(test)]
mod tests {
    use crate::abi::encode_abi_version;

    use super::PluginMetadata;

    #[test]
    fn new_sets_required_fields_and_defaults_optionals() {
        let m = PluginMetadata::new("gain", "0.1.0", "simple gain", encode_abi_version(1, 0));
        assert_eq!(m.name, "gain");
        assert_eq!(m.version, "0.1.0");
        assert_eq!(m.description, "simple gain");
        assert_eq!(m.author, None);
        assert_eq!(m.license, None);
        assert_eq!(m.abi_version, encode_abi_version(1, 0));
    }

    #[test]
    fn with_author_sets_author() {
        let m = PluginMetadata::new("gain", "0.1.0", "gain", 0).with_author("acme-audio");
        assert_eq!(m.author.as_deref(), Some("acme-audio"));
    }

    #[test]
    fn with_license_sets_license() {
        let m = PluginMetadata::new("gain", "0.1.0", "gain", 0).with_license("MIT");
        assert_eq!(m.license.as_deref(), Some("MIT"));
    }

    #[test]
    fn builders_chain() {
        let m = PluginMetadata::new("reverb", "1.2.3", "plate reverb", 1)
            .with_author("alice")
            .with_license("BSD-2-Clause");
        assert_eq!(m.name, "reverb");
        assert_eq!(m.author.as_deref(), Some("alice"));
        assert_eq!(m.license.as_deref(), Some("BSD-2-Clause"));
    }

    #[test]
    fn eq_clone_hold() {
        let a = PluginMetadata::new("g", "1", "d", 0);
        assert_eq!(a.clone(), a);
        let b = PluginMetadata::new("g", "1", "d", 0);
        assert_eq!(a, b);
        assert_ne!(a, PluginMetadata::new("g2", "1", "d", 0));
    }

    #[test]
    fn debug_includes_fields() {
        let m = PluginMetadata::new("gain", "0.1", "g", 1);
        let s = format!("{m:?}");
        assert!(s.contains("PluginMetadata"));
        assert!(s.contains("\"gain\""));
    }
}