856f865cf98d
served.rs
//! Fonts a host serves next to the app, fetched on demand (the web build: no system fonts, and
//! the wasm has no room for more embedded ones, see `build.rs`).
//!
//! The host lists them in `fonts/manifest.txt` next to `index.html`, in craft-fonts' manifest
//! format (`family | style | file | …`, the file relative to the site root), so a craft-fonts
//! checkout's `fonts/` folder works as it is and any other font needs one line. This module is
//! the part that doesn't depend on the platform: reading the manifest, the catalog of families
//! the host can serve, and the queue of families to fetch (picked in a font menu, or needed by a
//! layout). The web shell does the fetching and registers what arrives with
//! [`crate::FontDb::register_font_data`].
//!
//! Script fallback: the manifest's `scripts` field says which scripts a font is for. The first
//! served family listed for a script the bundled fonts don't cover (Arabic, Hebrew, Devanagari,
//! Thai, Khmer, Lao, Burmese, Georgian, Japanese, Chinese, Korean) is that script's fallback: text in that script asks for it
//! ([`request_for_text`], from layout), the font database puts it in the fallback stack once it
//! arrives, and the web shell asks up front for the scripts of the browser's languages
//! ([`request_for_languages`]). The manifest's SHA-256 becomes the fetch's Subresource Integrity
//! ([`ServedFont::integrity`]).
use std::sync::{Mutex, PoisonError};
/// One font file listed in a served font manifest.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ServedFont {
/// The family the file registers as (its typographic family name, `name` ID 16, else ID 1).
pub family: String,
/// Path relative to the site root, e.g. `fonts/open-sans/OpenSans-Regular.ttf`.
pub file: String,
/// ISO 15924 scripts the manifest lists for the file (`Arab`, `Jpan`, …); empty when absent.
pub scripts: Vec<String>,
/// Subresource Integrity value (`sha256-<base64>`) from the manifest's SHA-256, when it has a
/// valid one: the browser rejects any other bytes.
pub integrity: Option<String>,
}
/// Reads a manifest in craft-fonts' format: one font file per line, fields separated by ` | `
/// (`family | style | file | scripts | licence | licence file | sha256 | source`); `#` comments
/// and blank lines are ignored. Only family and file are needed here, so a line needs at least
/// `family | style | file`. Returns the fonts and, for each line that was skipped, why.
pub fn parse_manifest(text: &str) -> (Vec<ServedFont>, Vec<String>) {
let mut fonts = Vec::new();
let mut skipped = Vec::new();
for line in text.lines() {
let trimmed = line.trim();
if trimmed.is_empty() || trimmed.starts_with('#') {
continue;
}
let raw_fields: Vec<&str> = trimmed.split(" | ").collect();
let f: Vec<&str> = raw_fields.iter().map(|s| s.trim()).collect();
let raw_file = raw_fields.get(2).copied().unwrap_or("");
let valid_file = raw_file == f.get(2).copied().unwrap_or("") && is_relative_path(raw_file);
match f.as_slice() {
[family, _style, file, rest @ ..] if !family.is_empty() && valid_file => {
let scripts = rest.first().map(|s| s.split(',').map(str::trim).filter(|s| !s.is_empty()).map(str::to_string).collect()).unwrap_or_default();
let integrity = rest.get(3).and_then(|sha| sri(sha));
fonts.push(ServedFont { family: (*family).to_string(), file: (*file).to_string(), scripts, integrity });
}
[_, _, _, ..] if !valid_file => skipped.push(format!("{trimmed}: the file must be a relative path inside the site")),
_ => skipped.push(format!("{trimmed}: expected `family | style | file | …`")),
}
}
(fonts, skipped)
}
/// A relative path that stays inside the site: no scheme, no leading `/`, no `..` segment, no
/// query or fragment, no ASCII control characters or whitespace, and no percent-encoded control,
/// whitespace or separator characters.
pub fn is_relative_path(p: &str) -> bool {
if p.is_empty()
|| p.starts_with('/')
|| p.bytes().any(|b| b <= b' ' || b == 0x7f || matches!(b, b'\\' | b'?' | b'#' | b':'))
|| !p.split('/').all(|seg| !seg.is_empty() && seg != "." && seg != "..")
{
return false;
}
let b = p.as_bytes();
let mut decoded = Vec::with_capacity(b.len());
let mut i = 0;
while i < b.len() {
if b[i] == b'%' {
let Some(hex) = p.get(i + 1..i + 3) else { return false };
let Ok(byte) = u8::from_str_radix(hex, 16) else { return false };
// Never allow encoded path syntax (including '%' for a second decode), ASCII
// separators, or controls. High bytes are allowed only as valid UTF-8 below.
if byte <= b' ' || byte == 0x7f || matches!(byte, b'%' | b'/' | b'\\' | b'.' | b'?' | b'#' | b':') {
return false;
}
decoded.push(byte);
i = i.saturating_add(2);
} else {
let Some(&byte) = b.get(i) else { return false };
decoded.push(byte);
}
i = i.saturating_add(1);
}
std::str::from_utf8(&decoded).is_ok()
}
/// The scripts a served font can be the fallback for: those the bundled fonts (Inter, which covers
/// Latin, Greek and Cyrillic) lack, as ISO 15924 codes.
const FALLBACK_SCRIPTS: &[&str] = &["Arab", "Hebr", "Deva", "Thai", "Khmr", "Laoo", "Mymr", "Geor", "Jpan", "Hans", "Hant", "Kore"];
/// The script fallbacks in `fonts`: for each script in [`FALLBACK_SCRIPTS`], the first family in
/// manifest order that lists it, as `(script, family)` in order of first appearance.
pub fn script_fallbacks(fonts: &[ServedFont]) -> Vec<(String, String)> {
let mut out: Vec<(String, String)> = Vec::new();
for f in fonts {
for s in &f.scripts {
if FALLBACK_SCRIPTS.contains(&s.as_str()) && !out.iter().any(|(have, _)| have == s) {
out.push((s.clone(), f.family.clone()));
}
}
}
out
}
/// The fallback script of `c` (one of [`FALLBACK_SCRIPTS`]), or `None` for characters the bundled
/// fonts cover. Han follows `order` (the UI locale's CJK order), as the installed CJK fonts do.
pub fn script_of(c: char, order: &[crate::cjk::CjkScript; 4]) -> Option<&'static str> {
use crate::cjk::CjkScript;
if let Some(k) = crate::cjk::classify(c) {
return Some(match k.preferred(order) {
CjkScript::Japanese => "Jpan",
CjkScript::SimplifiedChinese => "Hans",
CjkScript::TraditionalChinese => "Hant",
CjkScript::Korean => "Kore",
});
}
Some(match c as u32 {
0x0590..=0x05FF | 0xFB1D..=0xFB4F => "Hebr",
0x0600..=0x06FF | 0x0750..=0x077F | 0x0870..=0x08FF | 0xFB50..=0xFDFF | 0xFE70..=0xFEFF | 0x1EE00..=0x1EEFF => "Arab",
0x0900..=0x097F | 0xA8E0..=0xA8FF => "Deva",
0x0E00..=0x0E7F => "Thai",
0x1780..=0x17FF | 0x19E0..=0x19FF => "Khmr",
0x0E80..=0x0EFF => "Laoo",
0x1000..=0x109F | 0xA9E0..=0xA9FF | 0xAA60..=0xAA7F => "Mymr",
0x10A0..=0x10FF | 0x1C90..=0x1CBF | 0x2D00..=0x2D2F => "Geor",
_ => return None,
})
}
/// The fallback script a browser language (`ar-EG`, `zh-Hant-TW`, …) is written in, if any.
pub fn language_script(tag: &str) -> Option<&'static str> {
let tag = tag.trim().to_ascii_lowercase().replace('_', "-");
let mut parts = tag.split('-');
let lang = parts.next()?;
let rest: Vec<&str> = parts.collect();
Some(match lang {
"ar" | "fa" | "ur" | "ps" | "ckb" | "sd" | "ug" => "Arab",
"he" | "iw" | "yi" => "Hebr",
"hi" | "mr" | "ne" | "sa" => "Deva",
"th" => "Thai",
"km" => "Khmr",
"lo" => "Laoo",
"my" => "Mymr",
"ka" => "Geor",
"ja" => "Jpan",
"ko" => "Kore",
"zh" if rest.iter().any(|r| matches!(*r, "hant" | "tw" | "hk" | "mo")) => "Hant",
"zh" => "Hans",
_ => return None,
})
}
/// The Subresource Integrity value (`sha256-<base64>`) for a 64-digit hex SHA-256.
fn sri(hex: &str) -> Option<String> {
if hex.len() != 64 || !hex.bytes().all(|b| b.is_ascii_hexdigit()) {
return None;
}
let bytes: Option<Vec<u8>> = (0..32).map(|i| hex.get(2 * i..2 * i + 2).and_then(|h| u8::from_str_radix(h, 16).ok())).collect();
Some(format!("sha256-{}", base64::Engine::encode(&base64::engine::general_purpose::STANDARD, bytes?)))
}
struct State {
/// Families the host can serve, installed or not.
families: Vec<String>,
/// Script fallbacks, `(script, family)`: the first one per script is used.
fallbacks: Vec<(String, String)>,
/// Families to fetch, not yet taken by [`take_requests`].
requested: Vec<String>,
/// Bumped when `families` changes, so font menus refresh.
generation: u64,
}
static STATE: Mutex<State> = Mutex::new(State { families: Vec::new(), fallbacks: Vec::new(), requested: Vec::new(), generation: 0 });
fn state() -> std::sync::MutexGuard<'static, State> {
STATE.lock().unwrap_or_else(PoisonError::into_inner)
}
/// Adds families the host can serve (the web shell, after reading the manifest).
pub fn add_families(families: impl IntoIterator<Item = String>) {
let mut s = state();
let before = s.families.len();
for f in families {
if !s.families.contains(&f) {
s.families.push(f);
}
}
if s.families.len() != before {
s.generation = s.generation.wrapping_add(1);
}
}
/// Adds the fonts of a manifest: their families (as [`add_families`]) and their script fallbacks.
pub fn add_fonts(fonts: &[ServedFont]) {
add_families(fonts.iter().map(|f| f.family.clone()));
let mut s = state();
for pair in script_fallbacks(fonts) {
if !s.fallbacks.contains(&pair) {
s.fallbacks.push(pair);
}
}
}
/// The served families that are some script's fallback (the font database adds the ones it has
/// to its fallback stack).
pub fn script_fallback_families() -> Vec<String> {
let mut v: Vec<String> = Vec::new();
for (_, f) in &state().fallbacks {
if !v.contains(f) {
v.push(f.clone());
}
}
v
}
/// The fallback family for `script`, if the host serves one.
fn fallback_for(fallbacks: &[(String, String)], script: &str) -> Option<String> {
fallbacks.iter().find(|(s, _)| s == script).map(|(_, f)| f.clone())
}
/// Asks for the served fallback families `text` needs: one per script in it that the bundled
/// fonts lack (called by layout; cheap when the host serves no script fallbacks).
pub fn request_for_text(text: &str) {
let fallbacks = state().fallbacks.clone();
if fallbacks.is_empty() {
return;
}
let order = crate::cjk::ui_script_order();
let mut asked: Vec<&'static str> = Vec::new();
for c in text.chars() {
if let Some(script) = script_of(c, &order)
&& !asked.contains(&script)
{
asked.push(script);
if let Some(family) = fallback_for(&fallbacks, script) {
request(&family);
}
}
}
}
/// Does `text` contain characters whose served fallback is `family`? (Type layers drawn before it
/// arrived are re-rendered.)
pub fn falls_back_to(text: &str, family: &str) -> bool {
let fallbacks = state().fallbacks.clone();
if !fallbacks.iter().any(|(_, f)| f == family) {
return false;
}
let order = crate::cjk::ui_script_order();
text.chars().any(|c| script_of(c, &order).and_then(|s| fallback_for(&fallbacks, s)).is_some_and(|f| f == family))
}
/// Asks up front for the fallback families of the scripts `languages` (the browser's, e.g.
/// `navigator.languages`) are written in, so text in them never waits for its font.
pub fn request_for_languages<'a>(languages: impl IntoIterator<Item = &'a str>) {
let fallbacks = state().fallbacks.clone();
for script in languages.into_iter().filter_map(language_script) {
if let Some(family) = fallback_for(&fallbacks, script) {
request(&family);
}
}
}
/// The served fallback family for the script `language` (a BCP 47 tag) is written in, if any.
pub fn fallback_for_language(language: &str) -> Option<String> {
fallback_for(&state().fallbacks, language_script(language)?)
}
/// Families the host can serve, installed or not (for font menus).
pub fn families() -> Vec<String> {
state().families.clone()
}
/// Changes whenever [`families`] does.
pub fn generation() -> u64 {
state().generation
}
/// Asks for a family to be fetched: picked in a font menu, or needed by a layout that doesn't
/// have it. Families the host doesn't serve are ignored; asking again is harmless.
pub fn request(family: &str) {
let mut s = state();
if s.families.iter().any(|f| f == family) && !s.requested.iter().any(|f| f == family) {
s.requested.push(family.to_string());
}
}
/// The families asked for since the last call (the web shell fetches each one once).
pub fn take_requests() -> Vec<String> {
std::mem::take(&mut state().requested)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn reads_craft_fonts_manifest_lines() {
let text = "# Font manifest for the Crafting Apps.\n\
\n\
BIZ UDPGothic | Regular | fonts/biz-ud-pgothic/BIZUDPGothic-Regular.ttf | Jpan,Latn | OFL-1.1 | fonts/biz-ud-pgothic/OFL.txt | 258d | https://example.org\n\
Open Sans | Regular | fonts/open-sans/OpenSans[wdth,wght].ttf\n";
let (fonts, skipped) = parse_manifest(text);
assert_eq!(
fonts,
[
ServedFont {
family: "BIZ UDPGothic".into(),
file: "fonts/biz-ud-pgothic/BIZUDPGothic-Regular.ttf".into(),
scripts: vec!["Jpan".into(), "Latn".into()],
integrity: None, // "258d" is not a SHA-256
},
ServedFont { family: "Open Sans".into(), file: "fonts/open-sans/OpenSans[wdth,wght].ttf".into(), scripts: vec![], integrity: None },
]
);
assert!(skipped.is_empty(), "{skipped:?}");
}
#[test]
fn skips_malformed_lines_and_paths_outside_the_site() {
let text = "Lato | Regular\n\
| Regular | fonts/x.ttf\n\
A | Regular | /fonts/a.ttf\n\
B | Regular | ../b.ttf\n\
C | Regular | fonts/../../c.ttf\n\
D | Regular | https://example.org/d.ttf\n\
E | Regular | fonts//e.ttf\n\
F | Regular | fonts\\f.ttf\n\
G | Regular | fonts/g.ttf?v=1\n\
Lato | Bold | fonts/lato/Lato-Bold.ttf\n";
let (fonts, skipped) = parse_manifest(text);
assert_eq!(fonts, [ServedFont { family: "Lato".into(), file: "fonts/lato/Lato-Bold.ttf".into(), scripts: vec![], integrity: None }]);
assert_eq!(skipped.len(), 9, "{skipped:?}");
}
#[test]
fn rejects_encoded_path_separators_and_malformed_escapes() {
for path in [
"fonts/%2e%2e/private.ttf",
"fonts%2fprivate.ttf",
"fonts%5cprivate.ttf",
"fonts/%00.ttf",
"fonts/a%7F.ttf",
"fonts/%20.ttf",
"fonts/%zz.ttf",
"fonts/%2.ttf",
"fonts/%C0%AF.ttf",
"fonts/%25%32%65%25%32%65/private.ttf",
"fonts/%C3%28.ttf",
] {
assert!(!is_relative_path(path), "accepted {path}");
}
for path in ["fonts/OpenSans[wdth,wght].ttf", "fonts/é.ttf", "fonts/%C3%A9.ttf"] {
assert!(is_relative_path(path), "rejected {path}");
}
let (fonts, skipped) = parse_manifest("A | Regular | fonts/%2e%2e/a.ttf\nB | Regular | fonts/%zz.ttf\n");
assert!(fonts.is_empty());
assert_eq!(skipped.len(), 2);
}
#[test]
fn requests_are_limited_to_the_catalog_and_reach_layout() {
let served = "Served Test Sans";
let g = generation();
add_families([served.to_string(), served.to_string()]);
assert_eq!(families().iter().filter(|f| *f == served).count(), 1);
assert_ne!(generation(), g, "the catalog changed");
let g = generation();
add_families([served.to_string()]);
assert_eq!(generation(), g, "nothing new");
request("Not Served Test Sans");
request(served);
request(served);
let taken = take_requests();
assert_eq!(taken.iter().filter(|f| *f == served).count(), 1, "{taken:?}");
assert!(!taken.iter().any(|f| f == "Not Served Test Sans"));
// A layout that needs a served family the database lacks asks for it (and is drawn with
// the fallback meanwhile).
let t = photocraft_doc::TextLayer { text: "Hi".into(), font_family: served.into(), size_pt: 12.0, ..Default::default() };
let l = crate::TextEngine::new().layout(&t, 72.0);
assert_eq!(l.glyphs.len(), 2);
assert!(take_requests().iter().any(|f| f == served));
// Script fallback: text in a script the bundled fonts lack asks for the served family
// that covers it (Hebrew here; other tests use other scripts, the state is shared).
let hebrew = "Served Test Hebrew";
let manifest = format!(
"{hebrew} | Regular | fonts/h/H.ttf | Hebr,Latn | OFL-1.1 | fonts/h/OFL.txt | {} | src\n",
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
);
add_fonts(&parse_manifest(&manifest).0);
assert!(families().iter().any(|f| f == hebrew), "add_fonts lists the family too");
assert!(script_fallback_families().iter().any(|f| f == hebrew));
let _ = take_requests();
request_for_text("Latin only, 123");
assert!(!take_requests().iter().any(|f| f == hebrew), "Latin text needs no served fallback");
request_for_text("Shalom שלום");
assert!(take_requests().iter().any(|f| f == hebrew), "Hebrew text asks for the Hebrew family");
assert!(falls_back_to("שלום", hebrew));
assert!(!falls_back_to("hello", hebrew));
// Startup preloading: a browser language using that script asks for it up front.
request_for_languages(["he-IL"]);
assert!(take_requests().iter().any(|f| f == hebrew));
request_for_languages(["en-US", "fr"]);
assert!(!take_requests().iter().any(|f| f == hebrew));
// A layout of Hebrew text in the default family asks for it too.
let t = photocraft_doc::TextLayer { text: "שלום".into(), size_pt: 12.0, ..Default::default() };
let _ = crate::TextEngine::new().layout(&t, 72.0);
assert!(take_requests().iter().any(|f| f == hebrew), "layout asks for the script fallback");
}
#[test]
fn manifest_scripts_and_sha256_become_scripts_and_integrity() {
let sha = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
let (fonts, _) = parse_manifest(&format!("Noto Sans Arabic | Regular | fonts/n/N.ttf | Arab | OFL-1.1 | fonts/n/OFL.txt | {sha} | src\n"));
assert_eq!(fonts[0].scripts, ["Arab"]);
assert_eq!(fonts[0].integrity.as_deref(), Some("sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="));
}
#[test]
fn the_first_served_family_per_script_is_its_fallback() {
let text = "Noto Sans Arabic | Regular | fonts/a.ttf | Arab\n\
Cairo | Regular | fonts/c.ttf | Arab,Latn\n\
Lobster | Regular | fonts/l.ttf | Latn,Cyrl\n\
BIZ UDPGothic | Regular | fonts/b.ttf | Jpan,Latn\n";
let (fonts, _) = parse_manifest(text);
assert_eq!(
script_fallbacks(&fonts),
[("Arab".to_string(), "Noto Sans Arabic".to_string()), ("Jpan".to_string(), "BIZ UDPGothic".to_string())],
"Latin and Cyrillic are the bundled fonts' job"
);
}
#[test]
fn characters_map_to_the_scripts_served_fonts_cover() {
use crate::cjk::CjkScript::*;
let ja = [Japanese, SimplifiedChinese, TraditionalChinese, Korean];
let zh = [SimplifiedChinese, TraditionalChinese, Japanese, Korean];
for (c, want) in [
('ب', Some("Arab")),
('ﻻ', Some("Arab")),
('ש', Some("Hebr")),
('क', Some("Deva")),
('ก', Some("Thai")),
('ខ', Some("Khmr")),
('ៗ', Some("Khmr")),
('ລ', Some("Laoo")),
('မ', Some("Mymr")),
('ၡ', Some("Mymr")),
('ა', Some("Geor")),
('あ', Some("Jpan")),
('한', Some("Kore")),
] {
assert_eq!(script_of(c, &ja), want, "{c}");
}
for c in ['a', 'Ж', 'Ω', '1', ' ', '€'] {
assert_eq!(script_of(c, &ja), None, "{c}: the bundled fonts cover it");
}
assert_eq!(script_of('漢', &ja), Some("Jpan"));
assert_eq!(script_of('漢', &zh), Some("Hans"));
}
#[test]
fn browser_languages_map_to_scripts() {
for (tag, want) in [
("ar", Some("Arab")),
("ar-EG", Some("Arab")),
("fa-IR", Some("Arab")),
("he", Some("Hebr")),
("km-KH", Some("Khmr")),
("lo", Some("Laoo")),
("my-MM", Some("Mymr")),
("ka-GE", Some("Geor")),
("ja-JP", Some("Jpan")),
("zh-CN", Some("Hans")),
("zh-TW", Some("Hant")),
("zh-Hant-HK", Some("Hant")),
("ko", Some("Kore")),
("en-US", None),
("ru", None),
] {
assert_eq!(language_script(tag), want, "{tag}");
}
}
#[test]
fn sri_rejects_non_hex_digits() {
let ok = "0".repeat(64);
assert!(sri(&ok).is_some());
let plus = format!("+f{}", "0".repeat(62));
assert!(sri(&plus).is_none());
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.