markdown.rs 96.7%

87 of 90 lines run, 26 of 30 functions · run #529 on main · run missed

//! Markdown to sanitised HTML: pulldown-cmark, then ammonia with an
//! allow-list (hub spec §15.2). Relative links and images are rebased on
//! `base`, so a README's `docs/x.md` opens in the hub.

use pulldown_cmark::{html, Event, Options, Parser, Tag};

/// Rendered Markdown by (text, link bases): 32 MiB.
fn cache() -> &'static super::cache::Lru<String> {
    static C: std::sync::OnceLock<super::cache::Lru<String>> = std::sync::OnceLock::new();
    C.get_or_init(|| super::cache::Lru::new(32 << 20))
}

/// (hits, misses, bytes) of the rendered Markdown cache.
pub fn cache_stats() -> (u64, u64, usize) {
    cache().stats()
}

/// `base_file` and `base_raw` are URL prefixes (ending in `/`) for links to
/// files and for images. Cached by the text and both bases.
pub fn render(text: &str, base_file: &str, base_raw: &str) -> String {
    let key = super::cache::key(&[b"md1", text.as_bytes(), base_file.as_bytes(), base_raw.as_bytes()]);
    cache().get_or(key, || render_uncached(text, base_file, base_raw)).as_ref().clone()
}

fn render_uncached(text: &str, base_file: &str, base_raw: &str) -> String {
    let mut opts = Options::empty();
    opts.insert(Options::ENABLE_TABLES);
    opts.insert(Options::ENABLE_STRIKETHROUGH);
    opts.insert(Options::ENABLE_TASKLISTS);
    opts.insert(Options::ENABLE_FOOTNOTES);
    opts.insert(Options::ENABLE_HEADING_ATTRIBUTES);
    let parser = Parser::new_ext(text, opts).map(|ev| match ev {
        Event::Start(Tag::Link { link_type, dest_url, title, id }) => {
            Event::Start(Tag::Link { link_type, dest_url: rebase(&dest_url, base_file).into(), title, id })
        }
        Event::Start(Tag::Image { link_type, dest_url, title, id }) => {
            let src = raw_image(&dest_url, &origin()).unwrap_or_else(|| rebase(&dest_url, base_raw));
            Event::Start(Tag::Image { link_type, dest_url: src.into(), title, id })
        }
        other => other,
    });
    let mut out = String::with_capacity(text.len() * 2);
    html::push_html(&mut out, parser);
    let mut builder = ammonia::Builder::default();
    builder.add_generic_attributes(["id", "class"]);
    builder.add_tag_attributes("input", ["type", "checked", "disabled"]);
    builder.add_tags(["input"]);
    builder.link_rel(Some("noopener noreferrer"));
    builder.clean(&out).to_string()
}

/// This hub's own origin (`https://oxygenhub.io`), so an image written as
/// a full address of one of its file pages is still recognised.
static ORIGIN: std::sync::RwLock<String> = std::sync::RwLock::new(String::new());

/// Set when the hub is built, from its base URL.
pub fn set_origin(base_url: &str) {
    *ORIGIN.write().unwrap() = base_url.trim_end_matches('/').to_string();
}

fn origin() -> String {
    ORIGIN.read().unwrap().clone()
}

/// An image that points at one of this hub's file pages
/// (`[ORIGIN]/OWNER/NAME/file/REF/PATH`, the address a file's page shows)
/// is that file's raw bytes (`…/raw/REF/PATH`): the page is HTML, which an
/// `<img>` cannot show, as GitHub turns `blob/` images into raw ones.
fn raw_image(url: &str, origin: &str) -> Option<String> {
    let (host, path) = if url.starts_with('/') && !url.starts_with("//") {
        ("", url)
    } else if !origin.is_empty() && url.strip_prefix(origin).is_some_and(|p| p.starts_with('/')) {
        (origin, &url[origin.len()..])
    } else {
        return None;
    };
    let mut parts = path[1..].splitn(4, '/');
    let (owner, name, kind, rest) = (parts.next()?, parts.next()?, parts.next()?, parts.next()?);
    (kind == "file" && !owner.is_empty() && !name.is_empty() && !rest.is_empty()).then(|| format!("{host}/{owner}/{name}/raw/{rest}"))
}

/// Leave absolute URLs, fragments and mail links alone; rebase the rest.
fn rebase(url: &str, base: &str) -> String {
    if url.starts_with('#') || url.contains("://") || url.starts_with("mailto:") || url.starts_with('/') || url.starts_with("data:") {
        return url.to_string();
    }
    let url = url.strip_prefix("./").unwrap_or(url);
    format!("{base}{url}")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn renders_and_sanitises() {
        let html = render(
            "# Hi\n\nSee [docs](docs/x.md) and ![i](img.png) <script>alert(1)</script>\n\n- [ ] task\n",
            "/a/b/file/main/",
            "/a/b/file/main/",
        );
        assert!(html.contains("<h1>Hi</h1>"));
        assert!(html.contains("href=\"/a/b/file/main/docs/x.md\""));
        assert!(html.contains("src=\"/a/b/file/main/img.png\""));
        assert!(!html.contains("<script"));
        assert!(html.contains("type=\"checkbox\""));
        assert!(render("[x](https://e.com) [y](#frag)", "/p/", "/p/").contains("href=\"https://e.com\""));
    }

    /// An image of one of this hub's file pages is its raw file: by full
    /// address or by path; another site's, a link, or a raw address stay.
    #[test]
    fn an_image_of_a_file_page_is_its_raw_file() {
        let o = "https://hub.example";
        assert_eq!(
            raw_image("https://hub.example/doomsdayone/tetriblox/file/main/docs/images/screens/menu.png", o).as_deref(),
            Some("https://hub.example/doomsdayone/tetriblox/raw/main/docs/images/screens/menu.png")
        );
        assert_eq!(raw_image("/a/b/file/v1.0/x.png", o).as_deref(), Some("/a/b/raw/v1.0/x.png"));
        assert_eq!(raw_image("https://elsewhere.example/a/b/file/main/x.png", o), None);
        assert_eq!(raw_image("https://hub.example.evil/a/b/file/main/x.png", o), None);
        assert_eq!(raw_image("/a/b/raw/main/x.png", o), None);
        assert_eq!(raw_image("//cdn.example/a/b/file/main/x.png", o), None);
        assert_eq!(raw_image("img.png", o), None);
        // Through render, with the origin set: only the image changes.
        set_origin("https://hub.example/");
        let html = render("[page](https://hub.example/a/b/file/main/x.png) ![x](https://hub.example/a/b/file/main/x.png)", "/p/", "/p/");
        assert!(html.contains("href=\"https://hub.example/a/b/file/main/x.png\""), "{html}");
        assert!(html.contains("src=\"https://hub.example/a/b/raw/main/x.png\""), "{html}");
    }
}

1		//! Markdown to sanitised HTML: pulldown-cmark, then ammonia with an
2		//! allow-list (hub spec §15.2). Relative links and images are rebased on
3		//! `base`, so a README's `docs/x.md` opens in the hub.
4
5		use pulldown_cmark::{html, Event, Options, Parser, Tag};
6
7		/// Rendered Markdown by (text, link bases): 32 MiB.
8	257×	fn cache() -> &'static super::cache::Lru<String> {
9		static C: std::sync::OnceLock<super::cache::Lru<String>> = std::sync::OnceLock::new();
10	257×	C.get_or_init(\|\| super::cache::Lru::new(32 << 20))
11	257×	}
12
13		/// (hits, misses, bytes) of the rendered Markdown cache.
14	0×	pub fn cache_stats() -> (u64, u64, usize) {
15	0×	cache().stats()
16	0×	}
17
18		/// `base_file` and `base_raw` are URL prefixes (ending in `/`) for links to
19		/// files and for images. Cached by the text and both bases.
20	257×	pub fn render(text: &str, base_file: &str, base_raw: &str) -> String {
21	257×	let key = super::cache::key(&[b"md1", text.as_bytes(), base_file.as_bytes(), base_raw.as_bytes()]);
22	257×	cache().get_or(key, \|\| render_uncached(text, base_file, base_raw)).as_ref().clone()
23	257×	}
24
25	61×	fn render_uncached(text: &str, base_file: &str, base_raw: &str) -> String {
26	61×	let mut opts = Options::empty();
27	61×	opts.insert(Options::ENABLE_TABLES);
28	61×	opts.insert(Options::ENABLE_STRIKETHROUGH);
29	61×	opts.insert(Options::ENABLE_TASKLISTS);
30	61×	opts.insert(Options::ENABLE_FOOTNOTES);
31	61×	opts.insert(Options::ENABLE_HEADING_ATTRIBUTES);
32	94×	let parser = Parser::new_ext(text, opts).map(\|ev\| match ev {
33	17×	Event::Start(Tag::Link { link_type, dest_url, title, id }) => {
34	17×	Event::Start(Tag::Link { link_type, dest_url: rebase(&dest_url, base_file).into(), title, id })
35		}
36	5×	Event::Start(Tag::Image { link_type, dest_url, title, id }) => {
37	5×	let src = raw_image(&dest_url, &origin()).unwrap_or_else(\|\| rebase(&dest_url, base_raw));
38	5×	Event::Start(Tag::Image { link_type, dest_url: src.into(), title, id })
39		}
40	281×	other => other,
41	303×	});
42	61×	let mut out = String::with_capacity(text.len() * 2);
43	61×	html::push_html(&mut out, parser);
44	61×	let mut builder = ammonia::Builder::default();
45	61×	builder.add_generic_attributes(["id", "class"]);
46	61×	builder.add_tag_attributes("input", ["type", "checked", "disabled"]);
47	61×	builder.add_tags(["input"]);
48	61×	builder.link_rel(Some("noopener noreferrer"));
49	61×	builder.clean(&out).to_string()
50	61×	}
51
52		/// This hub's own origin (`https://oxygenhub.io`), so an image written as
53		/// a full address of one of its file pages is still recognised.
54		static ORIGIN: std::sync::RwLock<String> = std::sync::RwLock::new(String::new());
55
56		/// Set when the hub is built, from its base URL.
57	203×	pub fn set_origin(base_url: &str) {
58	203×	*ORIGIN.write().unwrap() = base_url.trim_end_matches('/').to_string();
59	203×	}
60
61	5×	fn origin() -> String {
62	5×	ORIGIN.read().unwrap().clone()
63	5×	}
64
65		/// An image that points at one of this hub's file pages
66		/// (`[ORIGIN]/OWNER/NAME/file/REF/PATH`, the address a file's page shows)
67		/// is that file's raw bytes (`…/raw/REF/PATH`): the page is HTML, which an
68		/// `<img>` cannot show, as GitHub turns `blob/` images into raw ones.
69	12×	fn raw_image(url: &str, origin: &str) -> Option<String> {
70	12×	let (host, path) = if url.starts_with('/') && !url.starts_with("//") {
71	2×	("", url)
72	10×	} else if !origin.is_empty() && url.strip_prefix(origin).is_some_and(\|p\| p.starts_with('/')) {
73	2×	(origin, &url[origin.len()..])
74		} else {
75	8×	return None;
76		};
77	4×	let mut parts = path[1..].splitn(4, '/');
78	4×	let (owner, name, kind, rest) = (parts.next()?, parts.next()?, parts.next()?, parts.next()?);
79	4×	(kind == "file" && !owner.is_empty() && !name.is_empty() && !rest.is_empty()).then(\|\| format!("{host}/{owner}/{name}/raw/{rest}"))
80	12×	}
81
82		/// Leave absolute URLs, fragments and mail links alone; rebase the rest.
83	21×	fn rebase(url: &str, base: &str) -> String {
84	21×	if url.starts_with('#') \|\| url.contains("://") \|\| url.starts_with("mailto:") \|\| url.starts_with('/') \|\| url.starts_with("data:") {
85	9×	return url.to_string();
86	12×	}
87	12×	let url = url.strip_prefix("./").unwrap_or(url);
88	12×	format!("{base}{url}")
89	21×	}
90
91		#[cfg(test)]
92		mod tests {
93		use super::*;
94
95		#[test]
96	1×	fn renders_and_sanitises() {
97	1×	let html = render(
98	1×	"# Hi\n\nSee [docs](docs/x.md) and ![i](img.png) <script>alert(1)</script>\n\n- [ ] task\n",
99	1×	"/a/b/file/main/",
100	1×	"/a/b/file/main/",
101		);
102	1×	assert!(html.contains("<h1>Hi</h1>"));
103	1×	assert!(html.contains("href=\"/a/b/file/main/docs/x.md\""));
104	1×	assert!(html.contains("src=\"/a/b/file/main/img.png\""));
105	1×	assert!(!html.contains("<script"));
106	1×	assert!(html.contains("type=\"checkbox\""));
107	1×	assert!(render("[x](https://e.com) [y](#frag)", "/p/", "/p/").contains("href=\"https://e.com\""));
108	1×	}
109
110		/// An image of one of this hub's file pages is its raw file: by full
111		/// address or by path; another site's, a link, or a raw address stay.
112		#[test]
113	1×	fn an_image_of_a_file_page_is_its_raw_file() {
114	1×	let o = "https://hub.example";
115	1×	assert_eq!(
116	1×	raw_image("https://hub.example/doomsdayone/tetriblox/file/main/docs/images/screens/menu.png", o).as_deref(),
117		Some("https://hub.example/doomsdayone/tetriblox/raw/main/docs/images/screens/menu.png")
118		);
119	1×	assert_eq!(raw_image("/a/b/file/v1.0/x.png", o).as_deref(), Some("/a/b/raw/v1.0/x.png"));
120	1×	assert_eq!(raw_image("https://elsewhere.example/a/b/file/main/x.png", o), None);
121	1×	assert_eq!(raw_image("https://hub.example.evil/a/b/file/main/x.png", o), None);
122	1×	assert_eq!(raw_image("/a/b/raw/main/x.png", o), None);
123	1×	assert_eq!(raw_image("//cdn.example/a/b/file/main/x.png", o), None);
124	1×	assert_eq!(raw_image("img.png", o), None);
125		// Through render, with the origin set: only the image changes.
126	1×	set_origin("https://hub.example/");
127	1×	let html = render("[page](https://hub.example/a/b/file/main/x.png) ![x](https://hub.example/a/b/file/main/x.png)", "/p/", "/p/");
128	1×	assert!(html.contains("href=\"https://hub.example/a/b/file/main/x.png\""), "{html}");
129	1×	assert!(html.contains("src=\"https://hub.example/a/b/raw/main/x.png\""), "{html}");
130	1×	}
131		}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

Coverage / crates/hub/src/render/markdown.rs 96.7%

Keyboard