Skip to main content

reflex/pulse/
runtime.rs

1//! The Node runtime that builds Pulse sites, managed outside the rfx binary.
2//!
3//! ```text
4//! ~/.reflex/pulse/                      ($REFLEX_PULSE_HOME)
5//!   runtime/<deps-hash>/
6//!     package.json, package-lock.json   the template's pinned dependencies
7//!     node_modules/                     installed once per deps hash, shared by all projects
8//!     sites/<workspace-key>/            staged Astro project per workspace (template + bundle)
9//! ```
10//! The staged project sits under the runtime so Node's upward module resolution finds
11//! `node_modules` without links. The rfx binary embeds only the template sources
12//! (tens of KB); Node and `node_modules` never ship inside it.
13
14use crate::pulse::render::project::ProjectWriter;
15use anyhow::{Context, Result, bail};
16use std::io::{BufRead, BufReader};
17use std::path::{Path, PathBuf};
18use std::process::{Command, Stdio};
19use std::time::{Duration, Instant};
20
21/// The embedded site template.
22pub mod template {
23    include!(concat!(env!("OUT_DIR"), "/pulse_template.rs"));
24}
25
26/// Minimum Node version (Astro 7).
27pub const MIN_NODE: (u32, u32, u32) = (22, 12, 0);
28
29pub fn pulse_home() -> PathBuf {
30    if let Ok(h) = std::env::var("REFLEX_PULSE_HOME") {
31        return PathBuf::from(h);
32    }
33    dirs::home_dir()
34        .unwrap_or_else(|| PathBuf::from("."))
35        .join(".reflex")
36        .join("pulse")
37}
38
39#[derive(Debug, Clone)]
40pub struct Node {
41    pub path: PathBuf,
42    pub version: (u32, u32, u32),
43}
44
45pub fn parse_node_version(s: &str) -> Option<(u32, u32, u32)> {
46    let v = s.trim().trim_start_matches('v');
47    let mut it = v.split('.').map(|p| p.parse::<u32>().ok());
48    Some((it.next()??, it.next()??, it.next().flatten().unwrap_or(0)))
49}
50
51/// `$REFLEX_PULSE_NODE`, else `node` on `PATH`, at [`MIN_NODE`] or newer.
52pub fn find_node() -> Result<Node> {
53    let path = std::env::var("REFLEX_PULSE_NODE")
54        .map(PathBuf::from)
55        .unwrap_or_else(|_| PathBuf::from("node"));
56    let out = Command::new(&path)
57        .arg("--version")
58        .output()
59        .with_context(|| {
60            format!(
61                "Node.js {}.{}+ is needed to build the site and `{}` was not found.\n  \
62             Install Node (https://nodejs.org), or set REFLEX_PULSE_NODE, or run with --no-build \
63             to write the site project without building it.",
64                MIN_NODE.0,
65                MIN_NODE.1,
66                path.display()
67            )
68        })?;
69    let version = parse_node_version(&String::from_utf8_lossy(&out.stdout))
70        .context("could not read `node --version`")?;
71    if version < MIN_NODE {
72        bail!(
73            "Node {}.{}.{} is too old to build the site; {}.{}+ is needed (set REFLEX_PULSE_NODE to another node).",
74            version.0,
75            version.1,
76            version.2,
77            MIN_NODE.0,
78            MIN_NODE.1
79        );
80    }
81    Ok(Node { path, version })
82}
83
84/// An installed runtime: `node_modules` for the embedded template.
85#[derive(Debug, Clone)]
86pub struct Runtime {
87    pub root: PathBuf,
88    pub node: Node,
89}
90
91impl Runtime {
92    pub fn astro_entry(&self) -> PathBuf {
93        self.root.join("node_modules/astro/bin/astro.mjs")
94    }
95
96    /// Staging directory for one workspace.
97    pub fn site_dir(&self, workspace: &Path) -> PathBuf {
98        let canon = std::fs::canonicalize(workspace).unwrap_or_else(|_| workspace.to_path_buf());
99        let key = blake3::hash(canon.to_string_lossy().as_bytes()).to_hex()[..12].to_string();
100        let name = canon
101            .file_name()
102            .map(|n| crate::pulse::model::ids::slugify(&n.to_string_lossy()))
103            .unwrap_or_else(|| "site".into());
104        self.root.join("sites").join(format!("{name}-{key}"))
105    }
106}
107
108const COMPLETE: &str = ".pulse-runtime-complete";
109
110/// Find or install the runtime for the embedded template.
111///
112/// `$REFLEX_PULSE_RUNTIME` points at a directory with `node_modules` (CI caches,
113/// air-gapped mirrors). Otherwise the runtime lives under [`pulse_home`], keyed by the
114/// template's dependency hash, and is installed once with `npm ci --ignore-scripts`.
115pub fn ensure(offline: bool) -> Result<Runtime> {
116    let node = find_node()?;
117    if let Ok(dir) = std::env::var("REFLEX_PULSE_RUNTIME") {
118        let root = PathBuf::from(dir);
119        if !root.join("node_modules/astro").exists() {
120            bail!(
121                "REFLEX_PULSE_RUNTIME={} has no node_modules/astro",
122                root.display()
123            );
124        }
125        return Ok(Runtime { root, node });
126    }
127    let root = pulse_home().join("runtime").join(template::DEPS_HASH);
128    if root.join(COMPLETE).exists() {
129        return Ok(Runtime { root, node });
130    }
131    if offline {
132        bail!(
133            "The site runtime is not installed ({}) and --offline forbids installing it.\n  \
134             Run once without --offline, or use --no-build.",
135            root.display()
136        );
137    }
138    match install_prebuilt(&root) {
139        Ok(true) => {}
140        Ok(false) => install(&root, &node)?,
141        Err(e) => {
142            eprintln!("  prebuilt runtime unavailable ({e:#}); installing with npm instead");
143            install(&root, &node)?;
144        }
145    }
146    Ok(Runtime { root, node })
147}
148
149/// The runtime id: the template's dependency hash. It names the runtime directory,
150/// the prebuilt tarballs and their release tag.
151pub fn key() -> &'static str {
152    template::DEPS_HASH
153}
154
155/// A human-readable report for `rfx pulse runtime status`.
156pub fn status() -> String {
157    let mut out = String::new();
158    match find_node() {
159        Ok(n) => out.push_str(&format!(
160            "node:      {} ({}.{}.{})\n",
161            n.path.display(),
162            n.version.0,
163            n.version.1,
164            n.version.2
165        )),
166        Err(e) => out.push_str(&format!("node:      not usable: {e:#}\n")),
167    }
168    let root = pulse_home().join("runtime").join(key());
169    let state = if root.join(COMPLETE).exists() {
170        "installed"
171    } else {
172        "not installed"
173    };
174    out.push_str(&format!("runtime:   {} ({state})\n", root.display()));
175    let lock = RuntimeLock::embedded();
176    let platform = platform_id().unwrap_or("unsupported");
177    let prebuilt = match lock.asset_for(platform) {
178        Some(a) => format!("{} ({:.1} MB)", lock.url(a), a.size as f64 / 1_048_576.0),
179        None => "none published; falls back to npm ci".to_string(),
180    };
181    out.push_str(&format!("platform:  {platform}\nprebuilt:  {prebuilt}\n"));
182    out
183}
184
185/// The platform id Node reports (`process.platform-process.arch`), which names the
186/// prebuilt runtime tarballs.
187pub fn platform_id() -> Option<&'static str> {
188    Some(match (std::env::consts::OS, std::env::consts::ARCH) {
189        ("linux", "x86_64") => "linux-x64",
190        ("linux", "aarch64") => "linux-arm64",
191        ("macos", "x86_64") => "darwin-x64",
192        ("macos", "aarch64") => "darwin-arm64",
193        ("windows", "x86_64") => "win32-x64",
194        ("windows", "aarch64") => "win32-arm64",
195        _ => return None,
196    })
197}
198
199/// One published runtime tarball.
200#[derive(Debug, Clone, serde::Deserialize)]
201pub struct Asset {
202    pub name: String,
203    pub sha256: String,
204    #[serde(default)]
205    pub size: u64,
206}
207
208/// `pulse-template/runtime.lock.json`, compiled into the binary.
209#[derive(Debug, Clone, Default, serde::Deserialize)]
210pub struct RuntimeLock {
211    #[serde(default)]
212    pub deps_hash: String,
213    #[serde(default)]
214    pub release_base: String,
215    #[serde(default)]
216    pub assets: std::collections::BTreeMap<String, Asset>,
217}
218
219impl RuntimeLock {
220    pub fn embedded() -> Self {
221        serde_json::from_str(template::RUNTIME_LOCK).unwrap_or_default()
222    }
223
224    /// The asset for this platform, if the manifest matches the embedded template.
225    /// A stale manifest (template dependencies changed since the tarballs were built)
226    /// is ignored, so a new template never runs with old packages.
227    pub fn asset_for(&self, platform: &str) -> Option<&Asset> {
228        (self.deps_hash == template::DEPS_HASH)
229            .then(|| self.assets.get(platform))
230            .flatten()
231    }
232
233    /// Download URL; `REFLEX_PULSE_MIRROR` replaces the release base (air-gapped CI).
234    pub fn url(&self, asset: &Asset) -> String {
235        let base =
236            std::env::var("REFLEX_PULSE_MIRROR").unwrap_or_else(|_| self.release_base.clone());
237        format!(
238            "{}/pulse-runtime-{}/{}",
239            base.trim_end_matches('/'),
240            self.deps_hash,
241            asset.name
242        )
243    }
244}
245
246pub fn sha256_hex(bytes: &[u8]) -> String {
247    use sha2::{Digest, Sha256};
248    let mut h = Sha256::new();
249    h.update(bytes);
250    h.finalize().iter().map(|b| format!("{b:02x}")).collect()
251}
252
253/// Download, verify and unpack the prebuilt `node_modules` tarball. `Ok(false)` when
254/// no tarball is published for this platform and template.
255fn install_prebuilt(root: &Path) -> Result<bool> {
256    let lock = RuntimeLock::embedded();
257    let Some(asset) = platform_id().and_then(|p| lock.asset_for(p)) else {
258        return Ok(false);
259    };
260    std::fs::create_dir_all(root)?;
261    let guard =
262        crate::atomic_write::IndexLock::acquire_with_timeout(root, Duration::from_secs(900))
263            .context("waiting for another rfx process that is installing the site runtime")?;
264    if root.join(COMPLETE).exists() {
265        drop(guard);
266        return Ok(true);
267    }
268    let url = lock.url(asset);
269    eprintln!("Downloading the Pulse site runtime ({})…", asset.name);
270    let start = Instant::now();
271    let bytes = tokio::runtime::Builder::new_current_thread()
272        .enable_all()
273        .build()?
274        .block_on(async {
275            let resp = reqwest::get(&url).await?.error_for_status()?;
276            resp.bytes().await
277        })
278        .with_context(|| format!("downloading {url}"))?;
279    let got = sha256_hex(&bytes);
280    if !got.eq_ignore_ascii_case(&asset.sha256) {
281        bail!(
282            "checksum mismatch for {}: expected {}, got {got}",
283            asset.name,
284            asset.sha256
285        );
286    }
287    // Unpack beside the final location, then rename: a crash never leaves half a runtime.
288    let tmp = root.join(format!("node_modules.tmp-{}", std::process::id()));
289    let _ = std::fs::remove_dir_all(&tmp);
290    std::fs::create_dir_all(&tmp)?;
291    let decoder = zstd::stream::read::Decoder::new(&bytes[..])?;
292    let mut archive = tar::Archive::new(decoder);
293    for entry in archive.entries()? {
294        let mut entry = entry?;
295        // `unpack_in` refuses paths that escape `tmp` (`..`, absolute).
296        entry.unpack_in(&tmp)?;
297    }
298    let nm = tmp.join("node_modules");
299    if !nm.join("astro").exists() {
300        bail!("{} does not contain node_modules/astro", asset.name);
301    }
302    let _ = std::fs::remove_dir_all(root.join("node_modules"));
303    std::fs::rename(&nm, root.join("node_modules"))?;
304    let _ = std::fs::remove_dir_all(&tmp);
305    std::fs::write(root.join(COMPLETE), template::DEPS_HASH)?;
306    eprintln!(
307        "  runtime ready in {:.0}s ({:.1} MB)",
308        start.elapsed().as_secs_f64(),
309        bytes.len() as f64 / 1_048_576.0
310    );
311    drop(guard);
312    Ok(true)
313}
314
315fn npm_for(node: &Node) -> PathBuf {
316    // Prefer the npm that ships next to this node.
317    if let Some(dir) = node.path.parent().filter(|d| !d.as_os_str().is_empty()) {
318        for name in ["npm", "npm.cmd"] {
319            let p = dir.join(name);
320            if p.exists() {
321                return p;
322            }
323        }
324    }
325    PathBuf::from(if cfg!(windows) { "npm.cmd" } else { "npm" })
326}
327
328fn install(root: &Path, node: &Node) -> Result<()> {
329    std::fs::create_dir_all(root)?;
330    // Another rfx may be installing the same runtime; wait for it.
331    let lock = crate::atomic_write::IndexLock::acquire_with_timeout(root, Duration::from_secs(900))
332        .context("waiting for another rfx process that is installing the site runtime")?;
333    if root.join(COMPLETE).exists() {
334        drop(lock);
335        return Ok(());
336    }
337    for (rel, bytes) in template::FILES {
338        if *rel == "package.json" || *rel == "package-lock.json" {
339            std::fs::write(root.join(rel), bytes)?;
340        }
341    }
342    eprintln!(
343        "Installing the Pulse site runtime (Astro + Starlight) into {} — once per template version…",
344        root.display()
345    );
346    let start = Instant::now();
347    let status = Command::new(npm_for(node))
348        .args([
349            "ci",
350            "--ignore-scripts",
351            "--omit=dev",
352            "--no-audit",
353            "--no-fund",
354            "--loglevel=error",
355        ])
356        .current_dir(root)
357        .status()
358        .context("running `npm ci` (npm must be installed alongside node)")?;
359    if !status.success() {
360        bail!("`npm ci` failed in {} ({status})", root.display());
361    }
362    std::fs::write(root.join(COMPLETE), template::DEPS_HASH)?;
363    eprintln!("  runtime ready in {:.0}s", start.elapsed().as_secs_f64());
364    drop(lock);
365    Ok(())
366}
367
368/// Write the embedded template into `site_dir`; unchanged files keep their mtime.
369pub fn stage_template(site_dir: &Path) -> Result<()> {
370    let mut w = ProjectWriter::open(site_dir)?;
371    for (rel, bytes) in template::FILES {
372        if *rel == "package-lock.json" {
373            continue; // the runtime owns dependencies; a site has no node_modules
374        }
375        w.put(rel, bytes)?;
376    }
377    // Template files are never swept: only bundle files come and go.
378    w.finish("\0")?;
379    Ok(())
380}
381
382#[derive(Debug, Clone)]
383pub struct BuildOutcome {
384    pub dist: PathBuf,
385    pub elapsed: Duration,
386}
387
388/// Run `astro build` in `site_dir`. Output goes to `build.log`; a failure returns the
389/// last lines of it.
390pub fn astro_build(rt: &Runtime, site_dir: &Path, verbose: bool) -> Result<BuildOutcome> {
391    let start = Instant::now();
392    let log_path = site_dir.join("build.log");
393    let mut child = Command::new(&rt.node.path)
394        .arg(rt.astro_entry())
395        .args(["build", "--root"])
396        .arg(site_dir)
397        .current_dir(site_dir)
398        .env("ASTRO_TELEMETRY_DISABLED", "1")
399        .env("NODE_ENV", "production")
400        .stdout(Stdio::piped())
401        .stderr(Stdio::piped())
402        .spawn()
403        .context("starting astro build")?;
404    let stderr = child.stderr.take().expect("piped stderr");
405    let err_thread = std::thread::spawn(move || {
406        BufReader::new(stderr)
407            .lines()
408            .map_while(Result::ok)
409            .collect::<Vec<_>>()
410    });
411    let mut log: Vec<String> = Vec::new();
412    let stdout = child.stdout.take().expect("piped stdout");
413    for line in BufReader::new(stdout).lines().map_while(Result::ok) {
414        if verbose {
415            eprintln!("  {line}");
416        } else if line.contains("Complete!")
417            || line.contains("pages built in")
418            || line.contains("[build] ") && line.contains("page(s) built")
419        {
420            eprintln!("  {}", strip_ansi(&line));
421        }
422        log.push(line);
423    }
424    let status = child.wait()?;
425    log.extend(err_thread.join().unwrap_or_default());
426    let _ = std::fs::write(&log_path, log.join("\n"));
427    if !status.success() {
428        let tail: Vec<String> = log
429            .iter()
430            .rev()
431            .take(40)
432            .rev()
433            .map(|l| strip_ansi(l))
434            .collect();
435        bail!(
436            "astro build failed ({status}). Last lines of {}:\n{}",
437            log_path.display(),
438            tail.join("\n")
439        );
440    }
441    Ok(BuildOutcome {
442        dist: site_dir.join("dist"),
443        elapsed: start.elapsed(),
444    })
445}
446
447fn strip_ansi(s: &str) -> String {
448    let mut out = String::with_capacity(s.len());
449    let mut chars = s.chars().peekable();
450    while let Some(c) = chars.next() {
451        if c == '\u{1b}' {
452            for n in chars.by_ref() {
453                if n.is_ascii_alphabetic() {
454                    break;
455                }
456            }
457        } else {
458            out.push(c);
459        }
460    }
461    out
462}
463
464#[cfg(test)]
465mod tests {
466    use super::*;
467
468    #[test]
469    fn node_versions() {
470        assert_eq!(parse_node_version("v24.15.0\n"), Some((24, 15, 0)));
471        assert_eq!(parse_node_version("22.12"), Some((22, 12, 0)));
472        assert!(parse_node_version("v22.11.0").unwrap() < MIN_NODE);
473        assert!(parse_node_version("v22.12.0").unwrap() >= MIN_NODE);
474        assert_eq!(parse_node_version("nope"), None);
475    }
476
477    #[test]
478    fn template_is_embedded() {
479        let names: Vec<&str> = template::FILES.iter().map(|(n, _)| *n).collect();
480        for want in [
481            "astro.config.mjs",
482            "package.json",
483            "package-lock.json",
484            "src/layouts/PulsePage.astro",
485        ] {
486            assert!(names.contains(&want), "{want} missing from {names:?}");
487        }
488        assert!(
489            !names
490                .iter()
491                .any(|n| n.starts_with("node_modules/") || n.starts_with("scripts/"))
492        );
493        assert_eq!(template::DEPS_HASH.len(), 12);
494    }
495
496    #[test]
497    fn staging_writes_template_without_dependencies() {
498        let dir = tempfile::TempDir::new().unwrap();
499        stage_template(dir.path()).unwrap();
500        assert!(dir.path().join("astro.config.mjs").exists());
501        assert!(!dir.path().join("package-lock.json").exists());
502        assert!(
503            dir.path().join("package.json").exists(),
504            "declares \"type\": \"module\""
505        );
506    }
507
508    #[test]
509    fn runtime_lock_matching() {
510        let json = format!(
511            r#"{{"deps_hash": "{}", "release_base": "https://example.test/dl",
512                "assets": {{"linux-x64": {{"name": "a.tar.zst", "sha256": "ab", "size": 1}}}}}}"#,
513            template::DEPS_HASH
514        );
515        let lock: RuntimeLock = serde_json::from_str(&json).unwrap();
516        assert!(lock.asset_for("linux-x64").is_some());
517        assert!(lock.asset_for("darwin-arm64").is_none());
518        assert_eq!(
519            lock.url(lock.asset_for("linux-x64").unwrap()),
520            format!(
521                "https://example.test/dl/pulse-runtime-{}/a.tar.zst",
522                template::DEPS_HASH
523            )
524        );
525        let stale: RuntimeLock =
526            serde_json::from_str(r#"{"deps_hash": "000000000000", "assets": {"linux-x64": {"name": "a", "sha256": "b"}}}"#).unwrap();
527        assert!(
528            stale.asset_for("linux-x64").is_none(),
529            "a stale manifest is ignored"
530        );
531        // The committed manifest parses.
532        let _ = RuntimeLock::embedded();
533        assert_eq!(
534            sha256_hex(b"abc"),
535            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
536        );
537    }
538
539    #[test]
540    fn ansi_is_stripped() {
541        assert_eq!(strip_ansi("\u{1b}[32m✓ Complete!\u{1b}[39m"), "✓ Complete!");
542    }
543}