Skip to main content

fleetix_sidecar/
lib.rs

1//! Generic Pkl-to-Nix sidecar generation, shared by Fleetix and its consumers.
2
3use crate::fsutil::atomic_write;
4use miette::{IntoDiagnostic, Result, WrapErr};
5pub use pklx::pklr::EvalOptions;
6use std::path::{Path, PathBuf};
7
8mod cache;
9mod fsutil;
10
11/// Configure HTTP access for Pkl imports. Non-default HTTP settings bypass
12/// the persistent cache because their response content may change remotely.
13pub fn options_with_http(
14    http_rewrites: Vec<String>,
15    http_proxy: Option<&str>,
16) -> Result<EvalOptions> {
17    let mut options = EvalOptions {
18        http_rewrites,
19        ..EvalOptions::default()
20    };
21    if let Some(proxy_url) = http_proxy {
22        let proxy = pklx::pklr::ureq::Proxy::new(proxy_url)
23            .map_err(|error| miette::miette!("invalid proxy URL '{proxy_url}': {error}"))?;
24        options.agent = Some(
25            pklx::pklr::ureq::Agent::config_builder()
26                .proxy(Some(proxy))
27                .build()
28                .into(),
29        );
30    }
31    Ok(options)
32}
33
34/// Cache policy for a sidecar write. Cache failures fall back to evaluation.
35#[derive(Default)]
36pub struct CacheOptions {
37    /// Bypass the persistent cache when false (for example in validation checks).
38    pub enabled: bool,
39    /// Override the default `$XDG_CACHE_HOME/fleetix/pkl-to-nix` directory.
40    pub directory: Option<PathBuf>,
41}
42
43impl CacheOptions {
44    pub fn persistent() -> Self {
45        Self {
46            enabled: true,
47            directory: None,
48        }
49    }
50}
51
52#[derive(Debug, PartialEq, Eq)]
53pub struct WriteOutcome {
54    pub cached: bool,
55    pub changed: bool,
56}
57
58/// Render a Pkl file as an importable Nix expression.
59pub async fn render(path: &Path, options: EvalOptions) -> Result<String> {
60    pklx::eval_pkl(path, options).await
61}
62
63/// Compare a sidecar with a fresh render, without writing an output or cache.
64/// A missing destination is stale; other read and evaluation errors are reported.
65/// Comparison is byte-for-byte, including the generated-file header.
66pub async fn check(path: &Path, output: &Path, options: EvalOptions) -> Result<bool> {
67    let contents = sidecar_contents(&render(path, options).await?);
68    match std::fs::read(output) {
69        Ok(current) => Ok(current == contents.as_bytes()),
70        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
71        Err(error) => Err(error)
72            .into_diagnostic()
73            .wrap_err_with(|| format!("read sidecar {}", output.display())),
74    }
75}
76
77/// Synchronous read-only comparison for frontends outside a Tokio runtime.
78pub fn check_sync(path: &Path, output: &Path, options: EvalOptions) -> Result<bool> {
79    if tokio::runtime::Handle::try_current().is_ok() {
80        return Err(miette::miette!(
81            "synchronous Pkl checking cannot run inside a Tokio runtime; use check(...).await"
82        ));
83    }
84    let runtime = tokio::runtime::Runtime::new().into_diagnostic()?;
85    runtime.block_on(check(path, output, options))
86}
87
88/// Render and write a sidecar atomically. An unchanged output is left untouched.
89pub async fn write(path: &Path, output: &Path, options: EvalOptions) -> Result<WriteOutcome> {
90    write_with_cache(path, output, options, CacheOptions::persistent()).await
91}
92
93pub async fn write_with_cache(
94    path: &Path,
95    output: &Path,
96    options: EvalOptions,
97    cache_options: CacheOptions,
98) -> Result<WriteOutcome> {
99    let cache_location =
100        if cache_options.enabled && options.agent.is_none() && options.http_rewrites.is_empty() {
101            cache_options
102                .directory
103                .or_else(cache::default_dir)
104                .and_then(|dir| cache::key(path).ok().map(|key| (dir, key)))
105        } else {
106            None
107        };
108    if let Some((dir, key)) = &cache_location {
109        if let Some(nix) = cache::get(dir, key, None).await {
110            return Ok(WriteOutcome {
111                cached: true,
112                changed: write_rendered(output, &nix)?,
113            });
114        }
115    }
116
117    let (nix, snapshot) = cache::evaluate(path, options).await?;
118    // Never publish a cache entry for a failed sidecar write.
119    let changed = write_rendered(output, &nix)?;
120    if let Some((dir, key)) = &cache_location {
121        cache::put(dir, key, None, snapshot, &nix);
122    }
123    Ok(WriteOutcome {
124        cached: false,
125        changed,
126    })
127}
128
129/// Synchronous entry point for embedding in command-line tools.
130pub fn write_sync(path: &Path, output: &Path, options: EvalOptions) -> Result<WriteOutcome> {
131    write_with_cache_sync(path, output, options, CacheOptions::persistent())
132}
133
134/// Synchronous sidecar generation with explicit cache policy.
135pub fn write_with_cache_sync(
136    path: &Path,
137    output: &Path,
138    options: EvalOptions,
139    cache_options: CacheOptions,
140) -> Result<WriteOutcome> {
141    if tokio::runtime::Handle::try_current().is_ok() {
142        return Err(miette::miette!(
143            "synchronous Pkl generation cannot run inside a Tokio runtime; use write_with_cache(...).await"
144        ));
145    }
146    let runtime = tokio::runtime::Runtime::new().into_diagnostic()?;
147    runtime.block_on(write_with_cache(path, output, options, cache_options))
148}
149
150fn sidecar_contents(nix: &str) -> String {
151    format!("# Generated by fleetix; do not edit by hand.\n{nix}")
152}
153
154fn write_rendered(output: &Path, nix: &str) -> Result<bool> {
155    let contents = sidecar_contents(nix);
156    if std::fs::read(output).is_ok_and(|current| current == contents.as_bytes()) {
157        return Ok(false);
158    }
159    atomic_write(output, contents.as_bytes())?;
160    Ok(true)
161}
162
163#[cfg(test)]
164mod tests {
165    use super::*;
166    use std::fs;
167
168    fn cached(dir: &Path) -> CacheOptions {
169        CacheOptions {
170            enabled: true,
171            directory: Some(dir.to_path_buf()),
172        }
173    }
174
175    #[tokio::test]
176    async fn local_imports_invalidate_persistent_cache() {
177        let dir = tempfile::tempdir().unwrap();
178        let source = dir.path().join("Main.pkl");
179        let dependency = dir.path().join("Value.pkl");
180        let output = dir.path().join("generated.nix");
181        let cache_dir = dir.path().join("cache");
182        fs::write(&source, "import \"Value.pkl\" as V\nvalue = V.value\n").unwrap();
183        fs::write(&dependency, "value = 1\n").unwrap();
184
185        let generate =
186            || write_with_cache(&source, &output, EvalOptions::default(), cached(&cache_dir));
187        assert_eq!(
188            generate().await.unwrap(),
189            WriteOutcome {
190                cached: false,
191                changed: true
192            }
193        );
194        assert_eq!(
195            generate().await.unwrap(),
196            WriteOutcome {
197                cached: true,
198                changed: false
199            }
200        );
201
202        fs::write(&dependency, "value = 2\n").unwrap();
203        assert_eq!(
204            generate().await.unwrap(),
205            WriteOutcome {
206                cached: false,
207                changed: true
208            }
209        );
210        assert!(fs::read_to_string(&output).unwrap().contains("value = 2"));
211        assert_eq!(
212            generate().await.unwrap(),
213            WriteOutcome {
214                cached: true,
215                changed: false
216            }
217        );
218
219        fs::write(&output, "corrupted").unwrap();
220        assert_eq!(
221            generate().await.unwrap(),
222            WriteOutcome {
223                cached: true,
224                changed: true
225            }
226        );
227        assert!(fs::read_to_string(&output).unwrap().contains("value = 2"));
228
229        assert_eq!(
230            write_with_cache(
231                &source,
232                &output,
233                EvalOptions::default(),
234                CacheOptions::default()
235            )
236            .await
237            .unwrap(),
238            WriteOutcome {
239                cached: false,
240                changed: false
241            }
242        );
243    }
244
245    #[tokio::test]
246    async fn aggregate_cache_tracks_declared_imports_and_preserves_extensions() {
247        let dir = tempfile::tempdir().unwrap();
248        let topology = dir.path().join("topology");
249        fs::create_dir_all(topology.join("hosts")).unwrap();
250        fs::create_dir_all(dir.path().join("shared")).unwrap();
251        fs::write(
252            topology.join("Schema.pkl"),
253            "class Host { system: String }\n",
254        )
255        .unwrap();
256        fs::write(
257            dir.path().join("shared/Names.pkl"),
258            "names = new { site = \"first\" }\n",
259        )
260        .unwrap();
261        fs::write(topology.join("hosts/Hub.pkl"), "import \"../Schema.pkl\" as S\nhosts = new { hub = new S.Host { system = \"x86_64-linux\" } }\n").unwrap();
262        fs::write(
263            topology.join("Domains.pkl"),
264            "import \"../shared/Names.pkl\" as N\ndomains = new { site = N.names.site }\n",
265        )
266        .unwrap();
267        fs::write(topology.join("Services.pkl"), "services = new {}\n").unwrap();
268        let source = topology.join("Topology.aggregated.pkl");
269        fs::write(
270            &source,
271            "import \"hosts/Hub.pkl\" as H\nimport \"Domains.pkl\" as D\nschemaVersion = 2\nhosts = H.hosts\ndomains = D.domains\naccess = new { sshPort = 1337 }\ncustom = new { policy = \"preserved\" }\n",
272        )
273        .unwrap();
274        let output = dir.path().join("topology.nix");
275        let cache_dir = dir.path().join("cache");
276
277        let generate =
278            || write_with_cache(&source, &output, EvalOptions::default(), cached(&cache_dir));
279        assert_eq!(
280            generate().await.unwrap(),
281            WriteOutcome {
282                cached: false,
283                changed: true
284            }
285        );
286        assert_eq!(
287            generate().await.unwrap(),
288            WriteOutcome {
289                cached: true,
290                changed: false
291            }
292        );
293        fs::write(
294            dir.path().join("shared/Names.pkl"),
295            "names = new { site = \"second\" }\n",
296        )
297        .unwrap();
298        assert_eq!(
299            generate().await.unwrap(),
300            WriteOutcome {
301                cached: false,
302                changed: true
303            }
304        );
305        assert!(fs::read_to_string(&output).unwrap().contains("second"));
306        let rendered = fs::read_to_string(&output).unwrap();
307        assert!(rendered.contains("sshPort = 1337"));
308        assert!(rendered.contains("preserved"));
309        // Renaming the entrypoint must not change which data is exported.
310        let renamed = topology.join("Fleet.pkl");
311        fs::copy(&source, &renamed).unwrap();
312        assert_eq!(
313            render(&source, EvalOptions::default()).await.unwrap(),
314            render(&renamed, EvalOptions::default()).await.unwrap()
315        );
316    }
317
318    #[tokio::test]
319    async fn environment_reads_are_never_cached() {
320        let dir = tempfile::tempdir().unwrap();
321        let source = dir.path().join("Env.pkl");
322        let output = dir.path().join("env.nix");
323        fs::write(&source, "home = read(\"env:HOME\")\n").unwrap();
324        for _ in 0..2 {
325            assert!(
326                !write_with_cache(
327                    &source,
328                    &output,
329                    EvalOptions::default(),
330                    cached(&dir.path().join("cache")),
331                )
332                .await
333                .unwrap()
334                .cached
335            );
336        }
337    }
338
339    #[tokio::test]
340    async fn producer_upgrade_invalidates_receipt_without_rewriting_output() {
341        let dir = tempfile::tempdir().unwrap();
342        let source = dir.path().join("Source.pkl");
343        let output = dir.path().join("source.nix");
344        let cache_dir = dir.path().join("cache");
345        fs::write(&source, "value = 42\n").unwrap();
346        let generate =
347            || write_with_cache(&source, &output, EvalOptions::default(), cached(&cache_dir));
348        assert!(!generate().await.unwrap().cached);
349        assert!(generate().await.unwrap().cached);
350        let receipt = cache_dir.join(format!("{}.json", cache::key(&source).unwrap()));
351        let mut entry: serde_json::Value =
352            serde_json::from_slice(&fs::read(&receipt).unwrap()).unwrap();
353        entry["producer"] = "old-producer".into();
354        fs::write(&receipt, serde_json::to_vec(&entry).unwrap()).unwrap();
355        assert_eq!(
356            generate().await.unwrap(),
357            WriteOutcome {
358                cached: false,
359                changed: false
360            }
361        );
362        assert!(generate().await.unwrap().cached);
363    }
364}