1use indexmap::IndexMap;
19use schemars::JsonSchema;
20use serde::{Deserialize, Serialize};
21
22#[derive(
29 Debug, Clone, Serialize, Deserialize, PartialEq, JsonSchema, arbitrary::Arbitrary,
30)]
31#[schemars(rename = "agent.Plugin")]
32pub struct Plugin {
33 pub owner: String,
35 pub name: String,
37 pub version: String,
39 #[serde(default, skip_serializing_if = "Option::is_none")]
53 #[schemars(extend("omitempty" = true))]
54 #[arbitrary(with = crate::arbitrary_util::arbitrary_option_indexmap_string_json_value)]
55 pub arguments: Option<IndexMap<String, serde_json::Value>>,
56}
57
58impl Plugin {
59 fn sort_key(&self) -> String {
72 let arguments = self
73 .arguments
74 .as_ref()
75 .and_then(|arguments| serde_json::to_string(arguments).ok())
76 .unwrap_or_default();
77 format!(
78 "{}\0{}\0{}\0{arguments}",
79 self.owner, self.name, self.version,
80 )
81 }
82
83 pub fn validate(&self) -> Result<(), String> {
90 if self.owner.is_empty() {
91 return Err("`owner` cannot be empty".into());
92 }
93 if self.name.is_empty() {
94 return Err("`name` cannot be empty".into());
95 }
96 if self.version.is_empty() {
97 return Err("`version` cannot be empty".into());
98 }
99 if !self.version.starts_with('v') {
100 return Err(format!(
101 "`version` {:?} must start with 'v' — it is the plugin repo's git tag, Go-modules style (v1.2.3)",
102 self.version,
103 ));
104 }
105 if let Some(args) = self.arguments.as_ref() {
106 for (k, _) in args {
107 if k.is_empty() {
108 return Err("`arguments` key cannot be empty".into());
109 }
110 }
111 }
112 Ok(())
113 }
114}
115
116pub fn validate(plugins: &[Plugin]) -> Result<(), String> {
121 for plugin in plugins {
122 plugin.validate()?;
123 }
124 for (i, a) in plugins.iter().enumerate() {
125 for b in &plugins[i + 1..] {
126 if a.owner == b.owner && a.name == b.name && a.version == b.version
127 {
128 return Err(format!(
129 "`plugins` contains duplicate entry: \"{}/{}@{}\"",
130 a.owner, a.name, a.version,
131 ));
132 }
133 }
134 }
135 Ok(())
136}
137
138fn sort_object_keys(value: &mut serde_json::Value) {
165 match value {
166 serde_json::Value::Object(map) => {
167 for (_, nested) in map.iter_mut() {
168 sort_object_keys(nested);
169 }
170 map.sort_keys();
171 }
172 serde_json::Value::Array(items) => {
173 for item in items {
174 sort_object_keys(item);
175 }
176 }
177 _ => {}
178 }
179}
180
181pub fn prepare(mut plugins: Vec<Plugin>) -> Vec<Plugin> {
182 for plugin in &mut plugins {
183 plugin.owner = plugin.owner.to_lowercase();
184 plugin.name = plugin.name.to_lowercase();
185 let drop_empty = match plugin.arguments.as_mut() {
186 Some(args) => {
187 for (_, v) in args.iter_mut() {
188 if v.as_str() == Some("") {
191 *v = serde_json::Value::Null;
192 }
193 sort_object_keys(v);
194 }
195 args.sort_keys();
196 args.is_empty()
197 }
198 None => false,
199 };
200 if drop_empty {
201 plugin.arguments = None;
202 }
203 }
204 plugins.sort_by_cached_key(Plugin::sort_key);
208 plugins
209}
210
211#[cfg(test)]
212mod tests {
213 use super::*;
214
215 fn json_value(v: Option<&str>) -> serde_json::Value {
217 match v {
218 Some(s) => serde_json::Value::String(s.to_string()),
219 None => serde_json::Value::Null,
220 }
221 }
222
223 fn plugin(
224 owner: &str,
225 name: &str,
226 version: &str,
227 args: &[(&str, Option<&str>)],
228 ) -> Plugin {
229 let arguments = if args.is_empty() {
230 None
231 } else {
232 let mut m = IndexMap::new();
233 for (k, v) in args {
234 m.insert(k.to_string(), json_value(*v));
236 }
237 Some(m)
238 };
239 Plugin {
240 owner: owner.into(),
241 name: name.into(),
242 version: version.into(),
243 arguments,
244 }
245 }
246
247 #[test]
248 fn prepare_canonicalizes_arguments_and_sorts() {
249 let a = prepare(vec![
250 plugin("b", "x", "1", &[]),
251 plugin("a", "x", "1", &[("z", Some("1")), ("a", Some(""))]),
252 ]);
253 assert_eq!(a[0].owner, "a");
254 let args = a[0].arguments.as_ref().unwrap();
255 assert_eq!(
257 args.iter().map(|(k, _)| k.as_str()).collect::<Vec<_>>(),
258 vec!["a", "z"],
259 );
260 assert_eq!(args.get("a").unwrap(), &serde_json::Value::Null);
261 }
262
263 #[test]
265 fn arguments_carry_arbitrary_json() {
266 let mut arguments = IndexMap::new();
267 arguments.insert("retries".to_string(), serde_json::json!(3));
268 arguments.insert("verbose".to_string(), serde_json::json!(true));
269 arguments.insert("hosts".to_string(), serde_json::json!(["a", "b"]));
270 arguments.insert("nested".to_string(), serde_json::json!({"k": "v"}));
271 let prepared = prepare(vec![Plugin {
272 owner: "o".into(),
273 name: "n".into(),
274 version: "v1".into(),
275 arguments: Some(arguments),
276 }]);
277 let args = prepared[0].arguments.as_ref().unwrap();
278 assert_eq!(args.get("retries").unwrap(), &serde_json::json!(3));
279 assert_eq!(args.get("hosts").unwrap(), &serde_json::json!(["a", "b"]));
280 assert_eq!(args.get("nested").unwrap(), &serde_json::json!({"k": "v"}));
281 assert_eq!(
283 args.iter().map(|(k, _)| k.as_str()).collect::<Vec<_>>(),
284 vec!["hosts", "nested", "retries", "verbose"],
285 );
286 }
287
288 #[test]
292 fn prepare_sorts_object_keys_at_every_depth() {
293 let mut arguments = IndexMap::new();
294 arguments.insert(
295 "opts".to_string(),
296 serde_json::json!({"z": 1, "a": {"y": 2, "b": 3}}),
297 );
298 arguments.insert(
299 "list".to_string(),
300 serde_json::json!([{"q": 1, "p": 2}]),
301 );
302 let prepared = prepare(vec![Plugin {
303 owner: "o".into(),
304 name: "n".into(),
305 version: "v1".into(),
306 arguments: Some(arguments),
307 }]);
308 let args = prepared[0].arguments.as_ref().unwrap();
309 assert_eq!(
310 serde_json::to_string(args).unwrap(),
311 r#"{"list":[{"p":2,"q":1}],"opts":{"a":{"b":3,"y":2},"z":1}}"#,
312 );
313 }
314
315 #[test]
319 fn deeply_nested_orderings_canonicalize_identically() {
320 let build = |value: serde_json::Value| {
321 let mut arguments = IndexMap::new();
322 arguments.insert("k".to_string(), value);
323 prepare(vec![Plugin {
324 owner: "o".into(),
325 name: "n".into(),
326 version: "v1".into(),
327 arguments: Some(arguments),
328 }])
329 };
330 let a = build(serde_json::json!({"outer": [{"b": 1, "a": {"d": 2, "c": 3}}]}));
331 let b = build(serde_json::json!({"outer": [{"a": {"c": 3, "d": 2}, "b": 1}]}));
332 assert_eq!(
333 serde_json::to_string(&a).unwrap(),
334 serde_json::to_string(&b).unwrap(),
335 );
336 }
337
338 #[test]
341 fn prepare_preserves_array_element_order() {
342 let mut arguments = IndexMap::new();
343 arguments.insert("hosts".to_string(), serde_json::json!(["c", "a", "b"]));
344 let prepared = prepare(vec![Plugin {
345 owner: "o".into(),
346 name: "n".into(),
347 version: "v1".into(),
348 arguments: Some(arguments),
349 }]);
350 assert_eq!(
351 prepared[0].arguments.as_ref().unwrap().get("hosts").unwrap(),
352 &serde_json::json!(["c", "a", "b"]),
353 );
354 }
355
356 #[test]
359 fn prepare_orders_same_coordinates_by_arguments() {
360 let a = prepare(vec![
361 plugin("o", "n", "v1", &[("k", Some("b"))]),
362 plugin("o", "n", "v1", &[("k", Some("a"))]),
363 ]);
364 let values: Vec<_> = a
365 .iter()
366 .map(|p| p.arguments.as_ref().unwrap().get("k").unwrap().clone())
367 .collect();
368 assert_eq!(values, vec![serde_json::json!("a"), serde_json::json!("b")]);
369 }
370
371 #[test]
372 fn prepare_collapses_empty_arguments_to_none() {
373 let a = prepare(vec![Plugin {
374 owner: "o".into(),
375 name: "n".into(),
376 version: "1".into(),
377 arguments: Some(IndexMap::new()),
378 }]);
379 assert!(a[0].arguments.is_none());
380 }
381
382 #[test]
383 fn equivalent_declarations_canonicalize_identically() {
384 let a = prepare(vec![plugin(
385 "o",
386 "n",
387 "1",
388 &[("b", Some("1")), ("a", Some("2"))],
389 )]);
390 let b = prepare(vec![plugin(
391 "o",
392 "n",
393 "1",
394 &[("a", Some("2")), ("b", Some("1"))],
395 )]);
396 assert_eq!(
397 serde_json::to_string(&a).unwrap(),
398 serde_json::to_string(&b).unwrap(),
399 );
400 }
401
402 #[test]
403 fn prepare_lowercases_owner_and_name_but_not_version() {
404 let a = prepare(vec![plugin("Acme", "Widgets", "v1.2.3-RC1", &[])]);
405 let b = prepare(vec![plugin("acme", "widgets", "v1.2.3-RC1", &[])]);
406 assert_eq!(a[0].owner, "acme");
407 assert_eq!(a[0].name, "widgets");
408 assert_eq!(a[0].version, "v1.2.3-RC1");
410 assert_eq!(
411 serde_json::to_string(&a).unwrap(),
412 serde_json::to_string(&b).unwrap(),
413 );
414 }
415
416 #[test]
417 fn validate_rejects_duplicate_coordinates() {
418 let err = validate(&[
419 plugin("o", "n", "v1", &[]),
420 plugin("o", "n", "v1", &[("k", Some("v"))]),
421 ])
422 .expect_err("duplicate coordinates must be rejected");
423 assert!(err.contains("duplicate"), "unexpected error: {err}");
424 }
425
426 #[test]
427 fn validate_rejects_empty_fields() {
428 assert!(validate(&[plugin("", "n", "v1", &[])]).is_err());
429 assert!(validate(&[plugin("o", "", "v1", &[])]).is_err());
430 assert!(validate(&[plugin("o", "n", "", &[])]).is_err());
431 assert!(validate(&[plugin("o", "n", "v1", &[("", Some("v"))])]).is_err());
432 }
433
434 #[test]
437 fn validate_requires_v_prefixed_version() {
438 assert!(validate(&[plugin("o", "n", "1.2.3", &[])]).is_err());
439 assert!(validate(&[plugin("o", "n", "V1.2.3", &[])]).is_err());
442 assert!(validate(&[plugin("o", "n", "v1.2.3", &[])]).is_ok());
443 assert!(validate(&[plugin("o", "n", "v1.2.3-RC1", &[])]).is_ok());
444 }
445}