docs_pipeline/
embeds.rs

1//! Rich-media embed rendering.
2//!
3//! Renders whitelisted third-party embeds (YouTube, Figma, GitHub Gists,
4//! CodePen, tweets) into sandboxed iframes. Untrusted domains are blocked.
5
6use std::sync::LazyLock;
7
8static WHITELISTED_DOMAINS: LazyLock<Vec<&'static str>> = LazyLock::new(|| {
9    vec![
10        "www.youtube.com",
11        "youtube.com",
12        "youtu.be",
13        "www.figma.com",
14        "figma.com",
15        "gist.github.com",
16        "codepen.io",
17        "cdpn.io",
18        "platform.twitter.com",
19        "syndication.twitter.com",
20        "x.com",
21        "www.x.com",
22    ]
23});
24
25#[allow(dead_code)]
26const MAX_EMBEDS: usize = 10;
27
28/// Check whether a URL's domain is on the embed whitelist.
29pub fn is_domain_whitelisted(url: &str) -> bool {
30    WHITELISTED_DOMAINS.iter().any(|d| url.contains(d))
31}
32
33/// Count embed occurrences in content (skipping code blocks).
34pub fn count_embeds(content: &str) -> usize {
35    let mut count = 0;
36    let mut in_code_block = false;
37    for line in content.lines() {
38        if line.trim_start().starts_with("```") {
39            in_code_block = !in_code_block;
40            continue;
41        }
42        if in_code_block {
43            continue;
44        }
45        for alt in ["youtube", "figma", "gist", "codepen", "tweet"] {
46            let prefix = format!("![{}](", alt);
47            let mut rest = line;
48            while let Some(pos) = rest.find(&prefix) {
49                let after = &rest[pos + prefix.len()..];
50                if let Some(close) = after.find(')') {
51                    let url = &after[..close];
52                    if !url.trim().is_empty() {
53                        count += 1;
54                    }
55                    rest = &after[close + 1..];
56                } else {
57                    break;
58                }
59            }
60        }
61    }
62    count
63}
64
65/// Render a YouTube embed iframe for a video ID or URL.
66pub fn render_youtube(video_id: &str) -> String {
67    let video_id = video_id.trim();
68    if video_id.is_empty() {
69        return "<div class=\"embed-error\">YouTube embed: empty video ID</div>".to_string();
70    }
71    if !is_domain_whitelisted(video_id) && video_id.contains('/') {
72        return "<div class=\"embed-error\">YouTube embed blocked: untrusted URL</div>".to_string();
73    }
74    let id = video_id.split('/').next_back().unwrap_or(video_id);
75    format!(
76        r#"<div class="embed-youtube" data-video-id="{id}"><iframe src="https://www.youtube.com/embed/{id}" width="100%" height="360" frameborder="0" allowfullscreen loading="lazy" sandbox="allow-scripts allow-same-origin"></iframe></div>"#,
77        id = html_escape(id)
78    )
79}
80
81/// Render a Figma embed iframe for a whitelisted Figma URL.
82pub fn render_figma(url: &str) -> String {
83    let url = url.trim();
84    if !is_domain_whitelisted(url) {
85        return "<div class=\"embed-error\">Figma embed blocked: untrusted URL</div>".to_string();
86    }
87    format!(
88        r#"<div class="embed-figma"><iframe src="https://www.figma.com/embed?embed_host=share&url={url}" width="100%" height="450" frameborder="0" allowfullscreen loading="lazy" sandbox="allow-scripts allow-same-origin"></iframe></div>"#,
89        url = url_encode(url)
90    )
91}
92
93/// Render a GitHub Gist embed iframe for a whitelisted gist URL.
94pub fn render_gist(url: &str) -> String {
95    let url = url.trim();
96    if !is_domain_whitelisted(url) {
97        return "<div class=\"embed-error\">Gist embed blocked: untrusted URL</div>".to_string();
98    }
99    let raw = if url.ends_with(".js") {
100        url.to_string()
101    } else {
102        format!("{}.js", url)
103    };
104    format!(
105        r#"<div class="embed-gist"><iframe src="{raw}" width="100%" height="300" frameborder="0" loading="lazy" sandbox="allow-scripts allow-same-origin"></iframe></div>"#,
106        raw = html_escape(&raw)
107    )
108}
109
110/// Render a CodePen embed iframe for a whitelisted CodePen URL.
111pub fn render_codepen(url: &str) -> String {
112    let url = url.trim();
113    if !is_domain_whitelisted(url) {
114        return "<div class=\"embed-error\">CodePen embed blocked: untrusted URL</div>".to_string();
115    }
116    let embed_url = url
117        .replace("codepen.io/", "codepen.io/embed/")
118        .replace("cdpn.io/", "cdpn.io/embed/");
119    let embed_url = if !embed_url.contains("/embed/") {
120        format!("{}/embed/", url.trim_end_matches('/'))
121    } else {
122        embed_url
123    };
124    format!(
125        r#"<div class="embed-codepen"><iframe src="{embed_url}" width="100%" height="400" frameborder="0" loading="lazy" sandbox="allow-scripts allow-same-origin"></iframe></div>"#,
126        embed_url = html_escape(&embed_url)
127    )
128}
129
130/// Render a tweet embed blockquote for a whitelisted tweet URL.
131pub fn render_tweet(url: &str) -> String {
132    let url = url.trim();
133    if !is_domain_whitelisted(url) {
134        return "<div class=\"embed-error\">Tweet embed blocked: untrusted URL</div>".to_string();
135    }
136    format!(
137        r#"<div class="embed-tweet"><blockquote class="twitter-tweet" data-tweet-url="{url}"><a href="{url}">View Tweet</a></blockquote></div>"#,
138        url = html_escape(url)
139    )
140}
141
142fn html_escape(s: &str) -> String {
143    s.replace('&', "&amp;")
144        .replace('"', "&quot;")
145        .replace('<', "&lt;")
146        .replace('>', "&gt;")
147}
148
149fn url_encode(s: &str) -> String {
150    s.replace(' ', "%20")
151        .replace('"', "%22")
152        .replace('#', "%23")
153}
154
155/// Dispatch an embed render by `![alt](url)` alt name.
156///
157/// Returns `None` for unrecognized embed types.
158pub fn render_embed(alt: &str, url: &str) -> Option<String> {
159    Some(match alt {
160        "youtube" => render_youtube(url),
161        "figma" => render_figma(url),
162        "gist" => render_gist(url),
163        "codepen" => render_codepen(url),
164        "tweet" => render_tweet(url),
165        _ => return None,
166    })
167}
168
169/// CSP policy string for documents with embeds.
170pub fn embed_csp_policy() -> &'static str {
171    concat!(
172        "frame-src https://www.youtube.com https://youtube.com https://figma.com https://www.figma.com ",
173        "https://gist.github.com https://codepen.io https://cdpn.io ",
174        "https://platform.twitter.com https://syndication.twitter.com https://x.com https://www.x.com; ",
175        "script-src 'self' 'unsafe-inline' https://platform.twitter.com;"
176    )
177}
178
179#[cfg(test)]
180mod tests {
181    use super::*;
182
183    #[test]
184    fn test_youtube_render() {
185        let html = render_youtube("dQw4w9WgXcQ");
186        assert!(html.contains("embed-youtube"));
187        assert!(html.contains("youtube.com/embed/dQw4w9WgXcQ"));
188        assert!(html.contains("loading=\"lazy\""));
189        assert!(html.contains("sandbox=\"allow-scripts allow-same-origin\""));
190    }
191
192    #[test]
193    fn test_youtube_render_with_url() {
194        let html = render_youtube("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
195        assert!(html.contains("dQw4w9WgXcQ"));
196    }
197
198    #[test]
199    fn test_figma_render() {
200        let html = render_figma("https://www.figma.com/file/abc123");
201        assert!(html.contains("embed-figma"));
202        assert!(html.contains("figma.com/embed"));
203        assert!(html.contains("loading=\"lazy\""));
204    }
205
206    #[test]
207    fn test_gist_render() {
208        let html = render_gist("https://gist.github.com/user/abc123");
209        assert!(html.contains("embed-gist"));
210        assert!(html.contains("gist.github.com/user/abc123.js"));
211        assert!(html.contains("loading=\"lazy\""));
212    }
213
214    #[test]
215    fn test_codepen_render() {
216        let html = render_codepen("https://codepen.io/user/pen/abc123");
217        assert!(html.contains("embed-codepen"));
218        assert!(html.contains("codepen.io"));
219        assert!(html.contains("loading=\"lazy\""));
220    }
221
222    #[test]
223    fn test_tweet_render() {
224        let html = render_tweet("https://x.com/user/status/123456");
225        assert!(html.contains("embed-tweet"));
226        assert!(html.contains("twitter-tweet"));
227    }
228
229    #[test]
230    fn test_untrusted_domain_blocked() {
231        let html = render_youtube("https://evil.com/steal");
232        assert!(html.contains("blocked"));
233        assert!(!html.contains("<iframe"));
234
235        let html = render_figma("https://evil.com/fake");
236        assert!(html.contains("blocked"));
237
238        let html = render_gist("https://evil.com/fake");
239        assert!(html.contains("blocked"));
240
241        let html = render_codepen("https://evil.com/fake");
242        assert!(html.contains("blocked"));
243
244        let html = render_tweet("https://evil.com/fake");
245        assert!(html.contains("blocked"));
246    }
247
248    #[test]
249    fn test_domain_whitelist() {
250        assert!(is_domain_whitelisted("https://www.youtube.com/watch?v=123"));
251        assert!(is_domain_whitelisted("https://youtube.com/watch?v=123"));
252        assert!(is_domain_whitelisted("https://www.figma.com/file/abc"));
253        assert!(is_domain_whitelisted("https://gist.github.com/user/123"));
254        assert!(is_domain_whitelisted("https://codepen.io/user/pen/abc"));
255        assert!(is_domain_whitelisted("https://x.com/user/status/123"));
256        assert!(!is_domain_whitelisted("https://evil.com/malicious"));
257    }
258
259    #[test]
260    fn test_max_embed_count() {
261        let content = (0..15)
262            .map(|i| format!("![youtube](vid{})", i))
263            .collect::<Vec<_>>()
264            .join("\n");
265        assert_eq!(count_embeds(&content), 15);
266    }
267
268    #[test]
269    fn test_count_embeds_skips_code_blocks() {
270        let content = "![youtube](abc)\n```\n![youtube](xyz)\n```\n![figma](url)";
271        assert_eq!(count_embeds(content), 2);
272    }
273
274    #[test]
275    fn test_max_embeds_enforced() {
276        let mut embeds = Vec::new();
277        for i in 0..15 {
278            let url = format!("https://www.youtube.com/watch?v={}", i);
279            let count = embeds.len();
280            if count < MAX_EMBEDS {
281                embeds.push(render_youtube(&url));
282            }
283        }
284        assert_eq!(embeds.len(), MAX_EMBEDS);
285    }
286
287    #[test]
288    fn test_render_embed_dispatch() {
289        let html = render_embed("youtube", "abc123").unwrap();
290        assert!(html.contains("embed-youtube"));
291        assert!(render_embed("unknown", "abc123").is_none());
292    }
293
294    #[test]
295    fn test_csp_policy() {
296        let csp = embed_csp_policy();
297        assert!(csp.contains("frame-src"));
298        assert!(csp.contains("youtube.com"));
299        assert!(csp.contains("figma.com"));
300        assert!(csp.contains("twitter.com"));
301    }
302
303    #[test]
304    fn test_html_escape() {
305        assert_eq!(html_escape("a&b\"c<d>e"), "a&amp;b&quot;c&lt;d&gt;e");
306    }
307
308    #[test]
309    fn test_empty_url_returns_error() {
310        let html = render_youtube("");
311        assert!(
312            html.contains("empty") || html.contains("error"),
313            "Expected error for empty URL, got: {}",
314            html
315        );
316    }
317}
docs_pipeline/embeds.rs

docs_pipeline/
embeds.rs
