Skip to main content

cpa_plugin/store/
manifest.rs

1//! Store manifests (internal/pluginstore/manifest.go): what an installed plugin
2//! records under `plugins.configs.<id>.store`, and the Home sync manifests.
3
4use cpa_core::gostr::GoStr;
5use serde_yaml_ng::{Mapping, Value as Yaml};
6
7use super::client::Release;
8use super::registry::{
9    INSTALL_TYPE_DIRECT, INSTALL_TYPE_GITHUB_RELEASE, InstallPlan, Plugin, SCHEMA_VERSION_V2, Source,
10    normalize_install_plan, plugin_install_type, valid_plugin_id, valid_plugin_version, validate_install_plan,
11    validate_plugin,
12};
13use super::url;
14use super::version::normalize_version;
15use crate::go_struct;
16
17go_struct! {
18    pub struct Manifest("pluginstore.Manifest") {
19        "schema_version" omitempty => schema_version: isize,
20        "id" omitempty => id: String,
21        "name" omitempty => name: String,
22        "description" omitempty => description: String,
23        "author" omitempty => author: String,
24        "version" omitempty => version: String,
25        "release_tag" omitempty => release_tag: String,
26        "repository" omitempty => repository: String,
27        "logo" omitempty => logo: String,
28        "homepage" omitempty => homepage: String,
29        "license" omitempty => license: String,
30        "tags" omitempty => tags: Vec<String>,
31        "source_id" omitempty => source_id: String,
32        "source_name" omitempty => source_name: String,
33        "source_url" omitempty => source_url: String,
34        "install" omitempty => install: InstallPlan,
35    }
36}
37
38/// Go `ManifestFromRelease`.
39pub fn manifest_from_release(source: &Source, plugin: &Plugin, release: &Release) -> Result<Manifest, String> {
40    let version = release_version(release)?;
41    Ok(manifest_from_plugin_base(
42        source,
43        plugin,
44        Manifest {
45            version,
46            release_tag: release.tag_name.trim().to_owned(),
47            repository: plugin.repository.trim().to_owned(),
48            install: InstallPlan {
49                install_type: INSTALL_TYPE_GITHUB_RELEASE.into(),
50                ..Default::default()
51            },
52            ..Default::default()
53        },
54    ))
55}
56
57/// Go `ManifestFromPlugin`: direct installs only.
58pub fn manifest_from_plugin(source: &Source, plugin: &Plugin) -> Result<Manifest, String> {
59    validate_plugin(plugin)?;
60    match plugin_install_type(plugin).as_str() {
61        INSTALL_TYPE_DIRECT => {
62            let manifest = manifest_from_plugin_base(
63                source,
64                plugin,
65                Manifest {
66                    schema_version: SCHEMA_VERSION_V2,
67                    version: plugin.version.trim().to_owned(),
68                    install: normalize_install_plan(&plugin.install),
69                    ..Default::default()
70                },
71            );
72            manifest.validate()?;
73            Ok(manifest)
74        }
75        INSTALL_TYPE_GITHUB_RELEASE => Err("github-release manifest requires a resolved release".into()),
76        _ => Err(format!(
77            "unsupported install type {}",
78            cpa_common::gostr::quote(&plugin.install.install_type)
79        )),
80    }
81}
82
83fn manifest_from_plugin_base(source: &Source, plugin: &Plugin, mut base: Manifest) -> Manifest {
84    base.id = plugin.id.trim().to_owned();
85    base.name = plugin.name.trim().to_owned();
86    base.description = plugin.description.trim().to_owned();
87    base.author = plugin.author.trim().to_owned();
88    base.logo = plugin.logo.trim().to_owned();
89    base.homepage = plugin.homepage.trim().to_owned();
90    base.license = plugin.license.trim().to_owned();
91    base.tags = plugin.tags.clone();
92    base.source_id = source.id.trim().to_owned();
93    base.source_name = source.name.trim().to_owned();
94    base.source_url = source.url.trim().to_owned();
95    base
96}
97
98/// Go `ReleaseVersion`: the tag without its `v`, validated.
99pub fn release_version(release: &Release) -> Result<String, String> {
100    let version = normalize_version(&release.tag_name);
101    if !valid_plugin_version(&version) {
102        return Err(format!(
103            "invalid release tag {}",
104            cpa_common::gostr::quote(&release.tag_name)
105        ));
106    }
107    Ok(version)
108}
109
110/// yaml.v3 decoding of a scalar into a Go `string` (null is empty); containers fail.
111fn yaml_text(v: &Yaml) -> Option<String> {
112    match v {
113        Yaml::Null => Some(String::new()),
114        Yaml::Sequence(_) | Yaml::Mapping(_) => None,
115        Yaml::Tagged(t) => match &t.value {
116            Yaml::Sequence(_) | Yaml::Mapping(_) => None,
117            _ => Some(crate::config::yaml_string(&t.value)),
118        },
119        scalar => Some(crate::config::yaml_string(scalar)),
120    }
121}
122
123/// yaml.v3 decoding into a Go `int`/`int64` (null is 0).
124fn yaml_number(v: &Yaml) -> Option<i64> {
125    match v {
126        Yaml::Null => Some(0),
127        other => crate::config::yaml_int(other),
128    }
129}
130
131/// yaml.v3 decoding of the known `json`/`yaml` keys of a Go struct: `None` when a
132/// field fails to decode; unknown keys are ignored, as in Go.
133fn yaml_struct(v: &Yaml, mut field: impl FnMut(&str, &Yaml) -> Option<()>) -> Option<()> {
134    match v {
135        Yaml::Null => Some(()),
136        Yaml::Mapping(m) => m
137            .iter()
138            .try_for_each(|(key, value)| field(&crate::config::yaml_string(key), value)),
139        _ => None,
140    }
141}
142
143fn yaml_list<T>(v: &Yaml, item: impl Fn(&Yaml) -> Option<T>) -> Option<Vec<T>> {
144    match v {
145        Yaml::Null => Some(Vec::new()),
146        Yaml::Sequence(items) => items.iter().map(item).collect(),
147        _ => None,
148    }
149}
150
151fn yaml_artifact(v: &Yaml) -> Option<super::registry::Artifact> {
152    let mut a = super::registry::Artifact::default();
153    yaml_struct(v, |key, value| {
154        match key {
155            "goos" => a.goos = yaml_text(value)?,
156            "goarch" => a.goarch = yaml_text(value)?,
157            "url" => a.url = yaml_text(value)?,
158            "sha256" => a.sha256 = yaml_text(value)?,
159            "size" => a.size = yaml_number(value)?,
160            _ => {}
161        }
162        Some(())
163    })?;
164    Some(a)
165}
166
167impl Manifest {
168    /// Go `storeNode.Decode(&manifest)`: yaml.v3's typed decode of a saved store node
169    /// (`plugins.configs.<id>.store`). `None` when Go's decode fails.
170    // ponytail: merge keys and `!!binary` scalars are not interpreted.
171    pub fn from_yaml(node: &Yaml) -> Option<Manifest> {
172        let mut m = Manifest::default();
173        yaml_struct(node, |key, value| {
174            match key {
175                "schema-version" => m.schema_version = isize::try_from(yaml_number(value)?).ok()?,
176                "id" => m.id = yaml_text(value)?,
177                "name" => m.name = yaml_text(value)?,
178                "description" => m.description = yaml_text(value)?,
179                "author" => m.author = yaml_text(value)?,
180                "version" => m.version = yaml_text(value)?,
181                "release-tag" => m.release_tag = yaml_text(value)?,
182                "repository" => m.repository = yaml_text(value)?,
183                "logo" => m.logo = yaml_text(value)?,
184                "homepage" => m.homepage = yaml_text(value)?,
185                "license" => m.license = yaml_text(value)?,
186                "tags" => m.tags = yaml_list(value, yaml_text)?,
187                "source-id" => m.source_id = yaml_text(value)?,
188                "source-name" => m.source_name = yaml_text(value)?,
189                "source-url" => m.source_url = yaml_text(value)?,
190                "install" => {
191                    yaml_struct(value, |key, value| {
192                        match key {
193                            "type" => m.install.install_type = yaml_text(value)?,
194                            "artifacts" => m.install.artifacts = yaml_list(value, yaml_artifact)?,
195                            _ => {}
196                        }
197                        Some(())
198                    })?;
199                }
200                _ => {}
201            }
202            Some(())
203        })?;
204        Some(m)
205    }
206}
207
208impl Manifest {
209    /// Go `Manifest.Plugin`.
210    pub fn plugin(&self) -> Plugin {
211        Plugin {
212            id: self.id.trim().to_owned(),
213            name: self.name.trim().to_owned(),
214            description: self.description.trim().to_owned(),
215            author: self.author.trim().to_owned(),
216            version: self.version.trim().to_owned(),
217            repository: self.repository.trim().to_owned(),
218            logo: self.logo.trim().to_owned(),
219            homepage: self.homepage.trim().to_owned(),
220            license: self.license.trim().to_owned(),
221            tags: self.tags.clone(),
222            install: normalize_install_plan(&self.install),
223            ..Default::default()
224        }
225    }
226
227    /// Go `Manifest.InstallType`.
228    pub fn install_type(&self) -> String {
229        match self.install.install_type.trim().go_lower() {
230            t if t.is_empty() => INSTALL_TYPE_GITHUB_RELEASE.into(),
231            t => t,
232        }
233    }
234
235    /// Go `Manifest.Validate`.
236    pub fn validate(&self) -> Result<(), String> {
237        let version = self.version.trim();
238        if version.is_empty() {
239            return Err("missing required field version".into());
240        }
241        if !valid_plugin_version(&normalize_version(version)) {
242            return Err(format!(
243                "invalid plugin version {}",
244                cpa_common::gostr::quote(&self.version)
245            ));
246        }
247        match self.install_type().as_str() {
248            INSTALL_TYPE_DIRECT => {
249                if self.schema_version != 0 && self.schema_version != SCHEMA_VERSION_V2 {
250                    return Err(format!("unsupported schema-version {}", self.schema_version));
251                }
252                validate_manifest_plugin_id(&self.id)?;
253                let mut plan = normalize_install_plan(&self.install);
254                plan.install_type = INSTALL_TYPE_DIRECT.into();
255                if !plan.artifacts.is_empty() {
256                    validate_install_plan(&plan)?;
257                    return validate_pinned_artifact_urls(&plan);
258                }
259                validate_manifest_source_url(&self.source_url)
260            }
261            INSTALL_TYPE_GITHUB_RELEASE => {
262                let release_tag = self.release_tag.trim();
263                if release_tag.is_empty() {
264                    return Err("missing required field release-tag".into());
265                }
266                let mut plugin = self.plugin();
267                plugin.install = InstallPlan {
268                    install_type: INSTALL_TYPE_GITHUB_RELEASE.into(),
269                    ..Default::default()
270                };
271                validate_plugin(&plugin)?;
272                let release_version = release_version(&Release {
273                    tag_name: release_tag.into(),
274                    ..Default::default()
275                })?;
276                if release_version != normalize_version(version) {
277                    return Err(format!(
278                        "release-tag {} resolves version {}, want {}",
279                        cpa_common::gostr::quote(release_tag),
280                        cpa_common::gostr::quote(&release_version),
281                        cpa_common::gostr::quote(normalize_version(version))
282                    ));
283                }
284                Ok(())
285            }
286            _ => Err(format!(
287                "unsupported install type {}",
288                cpa_common::gostr::quote(&self.install.install_type)
289            )),
290        }
291    }
292
293    /// yaml.v3 `Encode` with the yaml tags: Go's field order, zero values omitted.
294    pub fn to_yaml(&self) -> Yaml {
295        let mut m = Mapping::new();
296        let mut text = |key: &str, value: &str| {
297            if !value.is_empty() {
298                m.insert(key.into(), value.into());
299            }
300        };
301        text("id", &self.id);
302        text("name", &self.name);
303        text("description", &self.description);
304        text("author", &self.author);
305        text("version", &self.version);
306        text("release-tag", &self.release_tag);
307        text("repository", &self.repository);
308        text("logo", &self.logo);
309        text("homepage", &self.homepage);
310        text("license", &self.license);
311        let mut out = Mapping::new();
312        if self.schema_version != 0 {
313            out.insert("schema-version".into(), (self.schema_version as i64).into());
314        }
315        out.extend(m);
316        if !self.tags.is_empty() {
317            out.insert(
318                "tags".into(),
319                Yaml::Sequence(self.tags.iter().map(|t| t.clone().into()).collect()),
320            );
321        }
322        for (key, value) in [
323            ("source-id", &self.source_id),
324            ("source-name", &self.source_name),
325            ("source-url", &self.source_url),
326        ] {
327            if !value.is_empty() {
328                out.insert(key.into(), value.clone().into());
329            }
330        }
331        let mut install = Mapping::new();
332        if !self.install.install_type.is_empty() {
333            install.insert("type".into(), self.install.install_type.clone().into());
334        }
335        if !self.install.artifacts.is_empty() {
336            let artifacts = self
337                .install
338                .artifacts
339                .iter()
340                .map(|a| {
341                    let mut item = Mapping::new();
342                    for (key, value) in [
343                        ("goos", &a.goos),
344                        ("goarch", &a.goarch),
345                        ("url", &a.url),
346                        ("sha256", &a.sha256),
347                    ] {
348                        if !value.is_empty() {
349                            item.insert(key.into(), value.clone().into());
350                        }
351                    }
352                    if a.size != 0 {
353                        item.insert("size".into(), a.size.into());
354                    }
355                    Yaml::Mapping(item)
356                })
357                .collect();
358            install.insert("artifacts".into(), Yaml::Sequence(artifacts));
359        }
360        if !install.is_empty() {
361            out.insert("install".into(), Yaml::Mapping(install));
362        }
363        Yaml::Mapping(out)
364    }
365}
366
367fn validate_pinned_artifact_urls(plan: &InstallPlan) -> Result<(), String> {
368    for (index, artifact) in plan.artifacts.iter().enumerate() {
369        let Some(parsed) = url::parse(artifact.url.trim()) else {
370            return Err(format!("artifacts[{index}]: invalid artifact url"));
371        };
372        if parsed.has_user {
373            return Err(format!(
374                "artifacts[{index}]: pinned artifact url must not contain credentials"
375            ));
376        }
377        if !parsed.raw_query.is_empty() || !parsed.fragment.is_empty() {
378            return Err(format!(
379                "artifacts[{index}]: pinned artifact url must not contain query or fragment"
380            ));
381        }
382    }
383    Ok(())
384}
385
386fn validate_manifest_plugin_id(id: &str) -> Result<(), String> {
387    let id = id.trim();
388    if id.is_empty() {
389        return Err("missing required field id".into());
390    }
391    if !valid_plugin_id(id) {
392        return Err(format!("invalid plugin id {}", cpa_common::gostr::quote(id)));
393    }
394    Ok(())
395}
396
397fn validate_manifest_source_url(source_url: &str) -> Result<(), String> {
398    let source_url = source_url.trim();
399    if source_url.is_empty() {
400        return Err("missing required field source-url".into());
401    }
402    let parsed = match url::parse(source_url) {
403        Some(u) if !u.scheme.is_empty() && !u.host.is_empty() => u,
404        _ => return Err("invalid source-url".into()),
405    };
406    if parsed.scheme != "https" && parsed.scheme != "http" {
407        return Err("source-url must use http or https".into());
408    }
409    if url::has_sensitive_query_parameter(&parsed) {
410        return Err("source-url contains sensitive query parameter".into());
411    }
412    Ok(())
413}