cargo-telar 0.2.2

Cargo subcommand for Telar apps: dev server with hot reload, and packaging into native installers.
//! `cargo telar build --target web --prerender`: every page of the site written ahead of time, by the app itself.
//!
//! The app is built once more for the machine running the build, with `telar/prerender`, and started once per page with the request in [`PRERENDER_ENV`]. What it writes back is filled into the same template the build already expanded, so a prerendered page differs from the plain one only in what the host element holds, the state it carries and the page's own language and title.

use std::collections::{BTreeMap, BTreeSet};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};

use telar_project::{
    PRERENDER_ENV, PageLocation, PageRequest, PrerenderRequest, PrerenderSection, PrerenderedPage,
};

use super::assets;
use super::negotiation;
use super::page::Page;
use super::site::{PageMeta, Site, SitePages};

/// The page a static host serves for an address it has no file for.
pub(super) const NOT_FOUND_FILE: &str = "404.html";

/// Builds the app's own binary for this machine, with the frontend `frontend` names and `telar/prerender`, and returns where cargo put it.
pub(super) fn build_host_binary(
    cargo_args: &[String],
    frontend: &[String],
    manifest_path: &Path,
) -> Result<PathBuf, String> {
    let mut args = vec![
        "build".to_string(),
        "--bins".to_string(),
        "--message-format=json-render-diagnostics".to_string(),
    ];
    args.extend(cargo_args.iter().filter(|a| *a != "--release").cloned());
    args.extend(frontend.iter().cloned());
    args.push("--features".to_string());
    args.push("telar/prerender".to_string());

    eprintln!("[cargo-telar] Building the app for this machine, to prerender its pages...");
    let output = Command::new("cargo")
        .args(&args)
        .stderr(Stdio::inherit())
        .output()
        .map_err(|e| format!("failed to invoke cargo: {e}"))?;
    if !output.status.success() {
        return Err("the prerender build failed".to_string());
    }
    executable_in(&String::from_utf8_lossy(&output.stdout), manifest_path).ok_or_else(|| {
        format!(
            "the prerender build produced no binary for {}. Does this package have a `[[bin]]` whose `main` calls `run()`?",
            manifest_path.display()
        )
    })
}

/// The binary cargo reports building for the package at `manifest_path`, from its JSON messages: the one named after the package when it has several.
fn executable_in(messages: &str, manifest_path: &Path) -> Option<PathBuf> {
    let mut found = Vec::new();
    for line in messages.lines() {
        let Ok(message) = serde_json::from_str::<serde_json::Value>(line) else {
            continue;
        };
        if message["reason"] != "compiler-artifact"
            || !same_file(
                Path::new(message["manifest_path"].as_str().unwrap_or_default()),
                manifest_path,
            )
        {
            continue;
        }
        let Some(executable) = message["executable"].as_str() else {
            continue;
        };
        let name = message["target"]["name"].as_str().unwrap_or_default();
        found.push((name.to_string(), PathBuf::from(executable)));
    }
    let package = package_name(manifest_path);
    found
        .iter()
        .find(|(name, _)| Some(name) == package.as_ref())
        .or_else(|| found.first())
        .map(|(_, path)| path.clone())
}

fn same_file(a: &Path, b: &Path) -> bool {
    match (a.canonicalize(), b.canonicalize()) {
        (Ok(a), Ok(b)) => a == b,
        _ => a == b,
    }
}

fn package_name(manifest: &Path) -> Option<String> {
    let text = std::fs::read_to_string(manifest).ok()?;
    let parsed: toml::Value = toml::from_str(&text).ok()?;
    parsed
        .get("package")?
        .get("name")?
        .as_str()
        .map(str::to_string)
}

/// Every page to write once the app has said which it has: each of its pages in each locale its address carries, or each page once when it carries none.
fn plan(discovered: &PrerenderedPage) -> Vec<PageLocation> {
    let mut pages: BTreeSet<PageLocation> = discovered
        .pages
        .iter()
        .map(|page| PageLocation {
            segments: page.segments.clone(),
            locale: None,
        })
        .collect();
    pages.insert(PageLocation::root());
    if discovered.locales.is_empty() {
        return pages.into_iter().collect();
    }
    discovered
        .locales
        .iter()
        .flat_map(|locale| pages.iter().map(move |page| page.in_locale(locale)))
        .collect()
}

/// Writes every page of the site into `out`, over the plain `index.html` the build already wrote, and a `404.html`, and says which it wrote.
///
/// Under an address that carries a locale, `/` is no page of its own: the root page negotiates the reader's locale and sends them to its root.
pub(super) fn write_pages(
    out: &Path,
    base: &Page,
    template: &str,
    binary: &Path,
    package_root: &Path,
    settings: &PrerenderSection,
    site: &Site,
) -> Result<SitePages, String> {
    let scratch_dir = crate::runner::scratch::scratch_dir("prerender")?;
    let scratch = scratch_dir.path();
    let run = |page: PageRequest, index: usize| -> Result<PrerenderedPage, String> {
        let request = PrerenderRequest {
            out: scratch.join(format!("page-{index}.json")),
            page,
            surface: settings.surface(),
            preferences: settings.preferences(),
            base: site.base().to_string(),
        };
        prerender(binary, package_root, &request)
    };

    let root = run(
        PageRequest::At {
            location: PageLocation::root(),
        },
        0,
    )?;
    let pages = site_pages(&root);
    let mut root_titles = BTreeMap::new();
    for (index, location) in pages.pages.iter().enumerate() {
        let page = match location == &PageLocation::root() {
            true => root.clone(),
            false => run(
                PageRequest::At {
                    location: location.clone(),
                },
                index + 1,
            )?,
        };
        if let (Some(locale), true) = (&location.locale, location.segments.is_empty()) {
            root_titles.insert(locale.clone(), page.title.clone());
        }
        let Some(file) = location.file() else {
            continue;
        };
        let filled = page_for(base, &page, site, Some(location), &pages);
        write_page(
            &out.join(file),
            &filled,
            template,
            location == &PageLocation::root(),
        )?;
    }
    if let Some(base_locale) = &pages.base_locale {
        let html = negotiation::root_page(site, &pages, base_locale, &root_titles);
        std::fs::write(out.join("index.html"), html)
            .map_err(|e| format!("could not write {}: {e}", out.join("index.html").display()))?;
    }
    let not_found = run(PageRequest::NotFound, usize::MAX)?;
    let filled = page_for(base, &not_found, site, None, &pages);
    write_page(&out.join(NOT_FOUND_FILE), &filled, template, false)?;
    Ok(pages)
}

/// The pages to write once the app has said which it has, and the locales its address carries; a page no file path can hold is left out, with a note.
fn site_pages(root: &PrerenderedPage) -> SitePages {
    let pages = plan(root)
        .into_iter()
        .filter(|location| {
            let held = location.file().is_some();
            if !held {
                eprintln!(
                    "[cargo-telar] skipping the page at /{}: a segment no file path can hold",
                    location.segments.join("/")
                );
            }
            held
        })
        .collect();
    let base_locale = match root.locales.is_empty() {
        true => None,
        false => root
            .base_locale
            .clone()
            .or_else(|| root.locales.first().cloned()),
    };
    SitePages {
        pages,
        locales: root.locales.clone(),
        base_locale,
        not_found: true,
        page_dirs: Vec::new(),
    }
}

/// Runs the app once for `request` and reads back the page it wrote.
fn prerender(
    binary: &Path,
    package_root: &Path,
    request: &PrerenderRequest,
) -> Result<PrerenderedPage, String> {
    let encoded = serde_json::to_string(request).map_err(|e| e.to_string())?;
    let status = Command::new(binary)
        .env(PRERENDER_ENV, encoded)
        .current_dir(package_root)
        .status()
        .map_err(|e| format!("could not start {}: {e}", binary.display()))?;
    if !status.success() {
        return Err(format!(
            "the app exited with {status} while prerendering {}",
            describe(&request.page)
        ));
    }
    let raw = std::fs::read(&request.out)
        .map_err(|e| format!("could not read {}: {e}", request.out.display()))?;
    let page: PrerenderedPage = serde_json::from_slice(&raw).map_err(|e| {
        format!(
            "the page the app wrote for {} could not be read: {e}",
            describe(&request.page)
        )
    })?;
    if !page.settled {
        eprintln!(
            "[cargo-telar] {} was still changing when it was written; it holds the frame it had reached",
            describe(&request.page)
        );
    }
    Ok(page)
}

fn describe(page: &PageRequest) -> String {
    match page {
        PageRequest::At { location } => {
            let locale = location
                .locale
                .as_deref()
                .map(|locale| format!("/{locale}"))
                .unwrap_or_default();
            format!("the page at {locale}/{}", location.segments.join("/"))
        }
        PageRequest::NotFound => "the page for a missing address".to_string(),
    }
}

/// The plain page with what the app wrote for one place filled in, and the tags that describe it. `location` is `None` for the page served at any address.
fn page_for(
    base: &Page,
    page: &PrerenderedPage,
    site: &Site,
    location: Option<&PageLocation>,
    pages: &SitePages,
) -> Page {
    let mut filled = base.clone();
    if let Some(lang) = &page.lang {
        filled.lang = lang.clone();
        filled.dir = layout_core::Direction::for_locale(lang);
    }
    if !page.title.is_empty() {
        filled.title = page.title.clone();
    }
    filled.base = site.base().to_string();
    filled.meta = site.head_tags(&PageMeta {
        title: &filled.title,
        lang: &filled.lang,
        location,
        pages,
    });
    filled.host = page.host_attributes.clone();
    filled.head.push(page.head.clone());
    filled.prerendered = page.markup.clone();
    filled.state = serde_json::to_value(&page.state).ok();
    filled
}

pub(super) fn write_page(
    path: &Path,
    page: &Page,
    template: &str,
    replace: bool,
) -> Result<(), String> {
    let html = page
        .render(template)
        .map_err(|e| format!("the page template: {e}"))?;
    if let Some(dir) = path.parent() {
        std::fs::create_dir_all(dir)
            .map_err(|e| format!("could not create {}: {e}", dir.display()))?;
    }
    if replace {
        return std::fs::write(path, html)
            .map_err(|e| format!("could not write {}: {e}", path.display()));
    }
    assets::write_new(path, html.as_bytes())
}

#[cfg(test)]
#[path = "prerender_test.rs"]
mod tests;