cargo-telar 0.2.3

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;

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

use crate::runner::artifacts::{self, build_with_diagnostics, with_json_messages};
use crate::runner::config::ResolvedPackage;

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],
    package: &ResolvedPackage,
) -> Result<PathBuf, String> {
    let args = host_binary_args(cargo_args, frontend);
    eprintln!("[cargo-telar] Building the app for this machine, to prerender its pages...");
    let (succeeded, report) = build_with_diagnostics(Command::new("cargo").args(&args));
    if !succeeded {
        return Err("the prerender build failed".to_string());
    }
    artifacts::binary(
        report.artifacts(),
        &package.package_dir,
        package.default_run.as_deref(),
    )
    .map_err(|e| format!("{e} The prerender runs the binary whose `main` calls `run()`."))
}

fn host_binary_args(cargo_args: &[String], frontend: &[String]) -> Vec<String> {
    let mut args = vec!["build".to_string(), "--bins".to_string()];
    args.extend(cargo_args.iter().cloned());
    args.extend(frontend.iter().cloned());
    args.push("--features".to_string());
    args.push("telar/prerender".to_string());
    with_json_messages(&mut args);
    args
}

/// 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_ref()
                .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 = i18n_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_html.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;