nexo-plugin-manifest 0.1.8

TOML manifest schema + 4-tier validator for native Rust nexo plugins (Phase 81.1).
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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

//! Phase 81.33.b.real Stage 4 — `[plugin.admin]` manifest section.
//!
//! Plugins that want to expose admin RPC methods (e.g. WhatsApp
//! `nexo/admin/whatsapp/bot/list`, Telegram bot-info commands,
//! email account inspectors) declare a method prefix in their
//! `nexo-plugin.toml`. The daemon's admin RPC dispatcher matches
//! every incoming method against the registered prefixes and
//! forwards matches to the plugin's subprocess via broker
//! JSON-RPC. The plugin handles internal dispatch.
//!
//! Replaces the previous pattern where each plugin needed a
//! hardcoded `.with_<plugin>_handle(Arc<dyn XxxHandle>)`
//! builder method on the admin dispatcher.
//!
//! ## Wire format
//!
//! Daemon → plugin on `<broker_topic_prefix>.<method_suffix>`:
//!
//! ```json
//! { "method": "<full-method-name>", "params": <params-json> }
//! ```
//!
//! Plugin replies:
//!
//! ```json
//! { "ok": true,  "result": <typed-result-json> }
//! { "ok": false, "error": "<message>" }
//! ```
//!
//! ## Method routing
//!
//! Daemon receives `method = "nexo/admin/whatsapp/bot/list"`.
//! With manifest `method_prefix = "nexo/admin/whatsapp/"` and
//! `broker_topic_prefix = "plugin.whatsapp.admin"`:
//!
//! 1. Strip prefix → `bot/list`.
//! 2. Replace `/` with `.` → `bot.list`.
//! 3. Append to broker prefix → `plugin.whatsapp.admin.bot.list`.
//! 4. Forward request + parse reply.

use serde::{Deserialize, Serialize};

/// Daemon-side admin RPC mount declaration.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct PluginAdminSection {
    /// Admin RPC method prefix the plugin owns. Must start with
    /// `nexo/admin/` (the canonical admin RPC namespace) and end
    /// with `/` so prefix matching is unambiguous. Example:
    /// `nexo/admin/whatsapp/`.
    pub method_prefix: String,

    /// Broker subject prefix the daemon forwards under. Example:
    /// `plugin.whatsapp.admin`. The daemon appends the
    /// method-suffix (with `/` → `.`) so a plugin handler
    /// subscribes to `<broker_topic_prefix>.<verb>`.
    pub broker_topic_prefix: String,

    /// Optional per-method broker RPC timeout. Default 30s.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout_seconds: Option<u64>,
}

impl PluginAdminSection {
    pub fn validate(&self) -> Result<(), String> {
        if !self.method_prefix.starts_with("nexo/admin/") {
            return Err(format!(
                "method_prefix must start with `nexo/admin/`; got `{}`",
                self.method_prefix
            ));
        }
        if !self.method_prefix.ends_with('/') {
            return Err(format!(
                "method_prefix must end with `/`; got `{}`",
                self.method_prefix
            ));
        }
        if self.method_prefix == "nexo/admin/" {
            return Err(
                "method_prefix `nexo/admin/` is the root namespace; declare a sub-prefix".into(),
            );
        }
        if self.broker_topic_prefix.is_empty() {
            return Err("broker_topic_prefix cannot be empty".into());
        }
        if self.broker_topic_prefix.contains(' ') {
            return Err("broker_topic_prefix cannot contain spaces".into());
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn validate_accepts_typical_prefix() {
        let s = PluginAdminSection {
            method_prefix: "nexo/admin/whatsapp/".into(),
            broker_topic_prefix: "plugin.whatsapp.admin".into(),
            timeout_seconds: None,
        };
        assert!(s.validate().is_ok());
    }

    #[test]
    fn validate_rejects_missing_admin_anchor() {
        let s = PluginAdminSection {
            method_prefix: "/whatsapp/".into(),
            broker_topic_prefix: "plugin.whatsapp".into(),
            timeout_seconds: None,
        };
        assert!(s.validate().is_err());
    }

    #[test]
    fn validate_rejects_missing_trailing_slash() {
        let s = PluginAdminSection {
            method_prefix: "nexo/admin/whatsapp".into(),
            broker_topic_prefix: "plugin.whatsapp".into(),
            timeout_seconds: None,
        };
        assert!(s.validate().is_err());
    }

    #[test]
    fn validate_rejects_root_namespace() {
        let s = PluginAdminSection {
            method_prefix: "nexo/admin/".into(),
            broker_topic_prefix: "plugin.foo".into(),
            timeout_seconds: None,
        };
        assert!(s.validate().is_err());
    }

    #[test]
    fn validate_rejects_empty_broker_topic() {
        let s = PluginAdminSection {
            method_prefix: "nexo/admin/whatsapp/".into(),
            broker_topic_prefix: String::new(),
            timeout_seconds: None,
        };
        assert!(s.validate().is_err());
    }

    #[test]
    fn deserializes_minimal_toml() {
        let toml = r#"
            method_prefix       = "nexo/admin/whatsapp/"
            broker_topic_prefix = "plugin.whatsapp.admin"
        "#;
        let s: PluginAdminSection = toml::from_str(toml).expect("parse");
        assert_eq!(s.method_prefix, "nexo/admin/whatsapp/");
        assert_eq!(s.broker_topic_prefix, "plugin.whatsapp.admin");
    }
}