cargo-telar 0.2.2

Cargo subcommand for Telar apps: dev server with hot reload, and packaging into native installers.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
//! Packaging for the browser: the wasm bundle, the page that loads it, and every other file the site serves.

use std::path::{Path, PathBuf};
use std::process::Command;

use telar_project::{FontDeclaration, PageLocation, WebHost, WebSection};

use super::{dist_dir, tool_missing};
use crate::runner::cli::{Target, WebRenderer};
use crate::runner::config::{
    TelarSection, WEB_PROFILE_TOML, find_package_dir, has_web_profile, resolve_package,
    split_android_flag,
};

mod addresses;
mod assets;
mod cloudflare;
mod fonts;
mod images;
mod media;
mod negotiation;
mod page;
mod prerender;
mod site;

use assets::{Assets, MANIFEST_FILE};
use page::{Bootstrap, DEFAULT_TEMPLATE, Page};
use site::{PageMeta, SITEMAP_FILE, Site, SitePages};

pub(crate) use media::{compressible, media_type};

/// The name `wasm-bindgen` gives its output, and what the generated page imports.
const BUNDLE: &str = "app";

/// The page every build writes at the output root.
const PAGE_FILE: &str = "index.html";

/// The target a browser module is built for, and what `wasm-bindgen` reads its output from.
pub(crate) const WASM_TARGET: &str = "wasm32-unknown-unknown";

/// The cargo profile a release web build uses, and the directory cargo then writes it to.
const WEB_PROFILE: &str = "web";

/// Builds the app for the browser: a wasm module, the JavaScript that instantiates it, and a page that starts it.
///
/// Three tools rather than one, because that is what the toolchain is: cargo produces a wasm module whose imports are `wasm-bindgen`'s ABI, `wasm-bindgen` writes the JavaScript that satisfies them, and `wasm-opt` shrinks the result. The first two are required; the third is skipped with a note if it is not installed.
pub(crate) fn build_web(
    cargo_args: Vec<String>,
    config: TelarSection,
    release: bool,
    renderer: Option<WebRenderer>,
    prerender: bool,
) -> ! {
    let out = match build_web_bundle(cargo_args, config, release, renderer, prerender) {
        Ok(out) => out,
        Err(e) => {
            eprintln!("[cargo-telar] {e}");
            std::process::exit(1);
        }
    };
    eprintln!("[cargo-telar] Packaged web build at {}", out.display());
    std::process::exit(0);
}

/// The same build, as a function that returns rather than exits — what `dev --target web` rebuilds with.
pub(crate) fn build_web_bundle(
    cargo_args: Vec<String>,
    config: TelarSection,
    release: bool,
    renderer: Option<WebRenderer>,
    prerender: bool,
) -> Result<PathBuf, String> {
    let pages = match prerender {
        true => SitePlan::Prerendered,
        false => SitePlan::Root,
    };
    build_web_site(
        cargo_args,
        config,
        &WebBuild {
            release,
            renderer,
            pages,
            out: None,
        },
    )
}

pub(crate) struct WebBuild<'a> {
    pub(crate) release: bool,
    pub(crate) renderer: Option<WebRenderer>,
    pub(crate) pages: SitePlan,
    /// Where the site is written; the workspace's `telar-dist/web` when `None`.
    pub(crate) out: Option<&'a Path>,
}

pub(crate) enum SitePlan {
    Root,
    /// Every page the app's routes list, written by the app itself; see `docs/prerender.md`.
    Prerendered,
    /// The plain page again at each of these addresses, and at `404.html`.
    Addresses(Vec<PageLocation>),
}

pub(crate) fn build_web_site(
    cargo_args: Vec<String>,
    config: TelarSection,
    build: &WebBuild,
) -> Result<PathBuf, String> {
    let WebBuild {
        release, renderer, ..
    } = *build;
    let (_android, rest) = split_android_flag(cargo_args);
    let resolved = resolve_package(&rest);
    let package_root = find_package_dir(&rest);
    // Assembled beside the output and swapped in whole, so the output only ever holds one build: every name in it is either this build's or gone, and a server reading it mid-build sees the last build rather than half of this one.
    let (out, staging) = match build.out {
        Some(out) => (out.to_path_buf(), staging_beside(out)?),
        None => {
            let dist = dist_dir(&resolved.workspace_root);
            (dist.join("web"), dist.join("web.staging"))
        }
    };

    // Checked before cargo ever runs: `--profile web` below would otherwise fail with cargo's own "profile `web` is not defined" error, which names neither the file to fix nor what to put in it.
    if release && !has_web_profile(&resolved.workspace_root) {
        return Err(format!(
            "this project's Cargo.toml has no `[profile.web]`, which a release web build needs (`cargo telar build --target web` passes `--profile web`). Add this to {}:\n\n{WEB_PROFILE_TOML}",
            resolved.workspace_root.join("Cargo.toml").display(),
        ));
    }

    let mut build_args = vec![
        "build".to_string(),
        "--target".to_string(),
        WASM_TARGET.to_string(),
        // The browser loads a module, not an executable: the `[lib]` target is what carries the app.
        "--lib".to_string(),
    ];
    build_args.extend(rest.iter().filter(|a| *a != "--release").cloned());
    if release {
        // Not `--release`: a module travels a network before it runs, and `[profile.web]` is release tuned for that rather than for a machine that already has the code.
        build_args.push("--profile".to_string());
        build_args.push(WEB_PROFILE.to_string());
    }
    // The renderers a window needs are not target-gated, so a default left on brings wgpu and a glyph shaper into a page that calls neither.
    let mut frontend = Vec::new();
    resolved
        .frontend_feature(Target::Web.feature(renderer))
        .push_to(&mut frontend);
    build_args.extend(frontend.iter().cloned());

    eprintln!("[cargo-telar] Building the wasm module...");
    let status = Command::new("cargo")
        .args(&build_args)
        .status()
        .map_err(|e| format!("failed to invoke cargo: {e}"))?;
    if !status.success() {
        return Err("the wasm build failed".to_string());
    }

    let profile = if release { WEB_PROFILE } else { "debug" };
    let module = telar_project::find_target_dir(&resolved.workspace_root)
        .join(WASM_TARGET)
        .join(profile)
        .join(format!("{}.wasm", resolved.name().replace('-', "_")));
    if !module.exists() {
        return Err(format!(
            "the build produced no wasm module at {}. Does this package have a `[lib]` target?",
            module.display()
        ));
    }

    recreate_dir(&staging)?;

    let locale = config.default_locale().unwrap_or_else(|| "en".to_string());
    let site = Site::new(&config.web, &package_root, &resolved.name())?;
    let host = config.web.host();
    run_wasm_bindgen(&module, &staging)?;
    optimise(&staging.join(format!("{BUNDLE}_bg.wasm")), release);
    let (page, template) = assemble(
        &staging,
        &package_root,
        &config.web,
        &config.fonts,
        &Shell {
            app_name: &resolved.name(),
            renderer,
            locale: &locale,
            site: &site,
            reserved: &reserved_paths(&build.pages, host),
        },
    )?;
    let pages = match &build.pages {
        SitePlan::Root => SitePages::root_only(),
        SitePlan::Prerendered => {
            let binary =
                prerender::build_host_binary(&rest, &frontend, &package_root.join("Cargo.toml"))?;
            let pages = prerender::write_pages(
                &staging,
                &page,
                &template,
                &binary,
                &package_root,
                &config.web.prerender,
                &site,
            )?;
            eprintln!(
                "[cargo-telar] Prerendered {} page(s) and a 404 page",
                pages.pages.len()
            );
            write_sitemap(&staging, &site, &pages)?;
            pages
        }
        SitePlan::Addresses(addresses) => {
            let pages = addresses::write_pages(&staging, &page, &template, &site, addresses)?;
            eprintln!(
                "[cargo-telar] Wrote {} page(s) and a 404 page",
                pages.pages.len()
            );
            pages
        }
    };
    images::ship_images(
        &staging,
        &images::local_crates(&resolved.workspace_root, &resolved.name())?,
    )?;
    ship_icon_notice(&staging, &package_root)?;
    match host {
        WebHost::Static if release => assets::precompress(&staging)?,
        WebHost::Static => {}
        WebHost::CloudflarePages => {
            cloudflare::write_host_files(&staging, &site, &pages)?;
            for (file, len) in cloudflare::oversized(&staging)? {
                eprintln!(
                    "[cargo-telar] warning: {file} is {:.1} MiB, and Cloudflare Pages serves no file over {} MiB",
                    len as f64 / (1024.0 * 1024.0),
                    cloudflare::MAX_FILE_BYTES / (1024 * 1024)
                );
            }
        }
    }
    publish(&staging, &out)?;
    Ok(out)
}

/// The paths a build writes itself, which a public file of the same name would collide with.
fn reserved_paths(pages: &SitePlan, host: WebHost) -> Vec<&'static str> {
    let mut reserved = vec![PAGE_FILE, MANIFEST_FILE, telar_baker::ICONS_NOTICE_FILENAME];
    match pages {
        SitePlan::Root => {}
        SitePlan::Prerendered => reserved.extend([prerender::NOT_FOUND_FILE, SITEMAP_FILE]),
        SitePlan::Addresses(_) => reserved.push(prerender::NOT_FOUND_FILE),
    }
    if host == WebHost::CloudflarePages {
        reserved.extend([cloudflare::WORKER_FILE, cloudflare::ROUTES_FILE]);
    }
    reserved
}

fn write_sitemap(out: &Path, site: &Site, pages: &SitePages) -> Result<(), String> {
    match site.sitemap(pages) {
        Some(sitemap) => assets::write_new(&out.join(SITEMAP_FILE), sitemap.as_bytes()),
        None => {
            eprintln!(
                "[cargo-telar] note: `[telar.web] origin` is not set, so the pages carry no canonical or alternate-language links and no sitemap is written"
            );
            Ok(())
        }
    }
}

/// What the page around the app is built from, beyond the project's own files.
struct Shell<'a> {
    app_name: &'a str,
    renderer: Option<WebRenderer>,
    /// The locale the plain page is written in.
    locale: &'a str,
    site: &'a Site,
    /// The paths of the output a public file may not take.
    reserved: &'a [&'a str],
}

/// The licence notice of the icons baked into the module, the application's and those of the crates it is built with, at the root of the site, where it is served beside what it describes.
fn ship_icon_notice(out: &Path, package_root: &Path) -> Result<(), String> {
    let Some(notice) = super::icon_notice(package_root) else {
        return Ok(());
    };
    std::fs::copy(&notice, out.join(telar_baker::ICONS_NOTICE_FILENAME))
        .map(|_| ())
        .map_err(|e| format!("could not copy {} into the site: {e}", notice.display()))
}

/// Everything after `wasm-bindgen`: the hashed bootstrap files, the public directory, the page and the manifest.
///
/// The module is hashed first and the glue after it is pointed at the module's new name, so the glue's own hash covers which module it loads: a new module is a new glue URL, and a page cached with the old one can never pair it with the new module.
fn assemble(
    out: &Path,
    package_root: &Path,
    web: &WebSection,
    fonts: &[FontDeclaration],
    shell: &Shell,
) -> Result<(Page, String), String> {
    let mut assets = Assets::new(out);
    let module = assets.adopt(&format!("{BUNDLE}_bg.wasm"))?;
    point_glue_at(&out.join(format!("{BUNDLE}.js")), &module)?;
    let glue = assets.adopt(&format!("{BUNDLE}.js"))?;

    let (public, named) = web.public_dir(package_root);
    if public.is_dir() {
        assets::copy_public(&public, out, shell.reserved)?;
    } else if named {
        return Err(format!(
            "`[telar.web] public` names {}, which is not a directory",
            public.display()
        ));
    }

    let mut page = Page::new(shell.app_name, Bootstrap { glue, module });
    page.lang = shell.locale.to_string();
    page.dir = layout_core::Direction::for_locale(shell.locale);
    page.renderer = shell.renderer;
    page.base = shell.site.base().to_string();
    page.meta = shell.site.head_tags(&PageMeta {
        title: shell.app_name,
        lang: shell.locale,
        location: Some(&PageLocation::root()),
        pages: &SitePages::root_only(),
    });
    fonts::declare_fonts(&mut page, &mut assets, package_root, fonts)?;
    let (template, origin) = read_template(web, package_root)?;
    let html = page
        .render(&template)
        .map_err(|e| format!("the page template ({origin}): {e}"))?;
    assets::write_new(&out.join(PAGE_FILE), html.as_bytes())?;
    assets.write_manifest()?;
    Ok((page, template))
}

/// The project's template, or the built-in page where the project has none at the default path. A path the project named that cannot be read is an error, never a quiet fallback.
fn read_template(web: &WebSection, package_root: &Path) -> Result<(String, String), String> {
    let (path, named) = web.template_path(package_root);
    match std::fs::read_to_string(&path) {
        Ok(template) => Ok((template, path.display().to_string())),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound && !named => Ok((
            DEFAULT_TEMPLATE.to_string(),
            "the built-in page".to_string(),
        )),
        Err(e) => Err(format!(
            "could not read the page template {}: {e}",
            path.display()
        )),
    }
}

/// Rewrites the glue's reference to the module `wasm-bindgen` named, so it fetches the hashed file instead.
fn point_glue_at(glue: &Path, module: &str) -> Result<(), String> {
    let plain = format!("'{BUNDLE}_bg.wasm'");
    let source = std::fs::read_to_string(glue)
        .map_err(|e| format!("could not read {}: {e}", glue.display()))?;
    let patched = source.replace(&plain, &format!("'{module}'"));
    if patched == source {
        return Err(format!(
            "the generated glue does not name {plain}, so the hashed module would never be fetched"
        ));
    }
    std::fs::write(glue, patched).map_err(|e| format!("could not write {}: {e}", glue.display()))
}

/// Where a build into `out` is assembled: beside it, so swapping it in is a rename.
fn staging_beside(out: &Path) -> Result<PathBuf, String> {
    check_site_dir(out)?;
    let mut staging = out.file_name().unwrap_or_default().to_os_string();
    staging.push(".staging");
    Ok(out.with_file_name(staging))
}

/// Whether a build may be written into `out`, which it replaces whole: a new or empty directory, or an earlier web build. Anything else is refused, since the swap would delete it.
pub(crate) fn check_site_dir(out: &Path) -> Result<(), String> {
    if out.file_name().is_none() {
        return Err(format!(
            "{} names no directory to write the site into",
            out.display()
        ));
    }
    if out.exists() && !holds_web_build_or_nothing(out)? {
        return Err(format!(
            "{} already holds files that are not a web build (it has no {MANIFEST_FILE}), and writing the site there would delete them; name a new or empty directory",
            out.display()
        ));
    }
    Ok(())
}

fn holds_web_build_or_nothing(dir: &Path) -> Result<bool, String> {
    if !dir.is_dir() {
        return Ok(false);
    }
    let mut entries =
        std::fs::read_dir(dir).map_err(|e| format!("could not read {}: {e}", dir.display()))?;
    Ok(entries.next().is_none() || dir.join(MANIFEST_FILE).is_file())
}

fn recreate_dir(dir: &Path) -> Result<(), String> {
    if dir.exists() {
        std::fs::remove_dir_all(dir)
            .map_err(|e| format!("could not clear {}: {e}", dir.display()))?;
    }
    std::fs::create_dir_all(dir).map_err(|e| format!("could not create {}: {e}", dir.display()))
}

fn publish(staging: &Path, out: &Path) -> Result<(), String> {
    if out.exists() {
        std::fs::remove_dir_all(out)
            .map_err(|e| format!("could not replace {}: {e}", out.display()))?;
    }
    std::fs::rename(staging, out).map_err(|e| {
        format!(
            "could not move {} to {}: {e}",
            staging.display(),
            out.display()
        )
    })
}

fn run_wasm_bindgen(module: &Path, out: &Path) -> Result<(), String> {
    let status = Command::new("wasm-bindgen")
        .arg("--target")
        .arg("web")
        .arg("--no-typescript")
        .arg("--out-dir")
        .arg(out)
        .arg("--out-name")
        .arg(BUNDLE)
        .arg(module)
        .status()
        .map_err(|e| {
            if e.kind() == std::io::ErrorKind::NotFound {
                tool_missing(
                    "wasm-bindgen",
                    "cargo install wasm-bindgen-cli --version <the version in your Cargo.lock>",
                )
            } else {
                format!("failed to invoke wasm-bindgen: {e}")
            }
        })?;
    if !status.success() {
        return Err("wasm-bindgen failed".to_string());
    }
    Ok(())
}

/// Shrinks the module in place. Optional: a build that skips it works, it is just larger.
fn optimise(module: &Path, release: bool) {
    if !release {
        return;
    }
    let tmp = module.with_extension("opt.wasm");
    let status = Command::new("wasm-opt")
        .args([
            "-Oz",
            "--enable-bulk-memory",
            "--enable-nontrapping-float-to-int",
        ])
        .arg("-o")
        .arg(&tmp)
        .arg(module)
        .status();
    match status {
        Ok(status) if status.success() => {
            let _ = std::fs::rename(&tmp, module);
        }
        Ok(_) => {
            let _ = std::fs::remove_file(&tmp);
            eprintln!("[cargo-telar] wasm-opt failed; shipping the unoptimised module.");
        }
        Err(_) => eprintln!(
            "[cargo-telar] wasm-opt is not installed, so the module is shipped unoptimised (install `binaryen` for a smaller one)."
        ),
    }
}

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