Skip to main content

dustnet_server/
include.rs

1//! Resolving `[include name=...]` placeholders into generated content.
2//!
3//! A page may name places a server fills: `[include name="links" /]`. This
4//! module replaces those placeholders before the page goes on the wire, and it
5//! is the only thing in the server that turns a request into generated markup.
6//!
7//! # What this does not do
8//!
9//! It does not make the server dynamic in the sense
10//! [`docs/spec/07-security.md`](../../../docs/spec/07-security.md) rules out. A
11//! resolver cannot see the connection, the peer, the session or the filesystem
12//! — it is handed a name and a request path and returns tokens. `INPUT` is
13//! still refused with 405, there is no authentication, and `dustnetd` passes no
14//! resolver at all, so its behaviour is byte-for-byte what it was: an
15//! `[include]` reaches the client, which renders it as nothing.
16//!
17//! # Why tokens rather than a string
18//!
19//! A resolver returns [`Token`]s and never text. That is the whole safety
20//! argument: user-submitted content becomes a [`Token::Text`], and
21//! [`to_aml`] is the single place that writes a `[`, so a comment body cannot
22//! become a `[form]` however hostile it is. A resolver returning `String` would
23//! put the escaping burden back on every handler, which is the mistake an
24//! earlier prototype of this project made — see [`dustnet_core::serialize`].
25//!
26//! # One pass, no recursion
27//!
28//! Resolution walks the authored token stream once. Tokens a resolver returns
29//! are spliced in and **not** rescanned, and a resolver that returns an
30//! `[include]` is an error rather than a second round: an include resolving to
31//! an include is either a mistake or an attempt to make the server loop, and
32//! neither deserves support.
33
34use dustnet_core::protocol::ProtocolError;
35use dustnet_core::scanner::{Scanner, Token};
36use dustnet_core::serialize::to_aml;
37
38/// The element name a placeholder uses, and the attribute naming its handler.
39const INCLUDE_TAG: &str = "include";
40const NAME_ATTR: &str = "name";
41
42/// What a resolver is told about the request being served.
43///
44/// Deliberately thin. A resolver gets the path, the query and who is asking —
45/// no peer address, no headers, no connection, and **no session token** — so
46/// that generating a page cannot widen what a site learns about its reader, and
47/// cannot leak a bearer credential into the page it produces.
48#[derive(Debug, Clone, Copy)]
49pub struct IncludeRequest<'a> {
50    /// The requested path, as it appeared in the GET.
51    pub path: &'a str,
52    /// The query string, without the leading `?`, if the request carried one.
53    pub query: Option<&'a str>,
54    /// Who is asking, resolved from their session token, or `None` for
55    /// anonymous. A token that did not resolve is `None` too: a resolver must
56    /// not be able to tell "unknown token" from "no token".
57    pub identity: Option<&'a str>,
58}
59
60/// Produces content for named `[include]` placeholders.
61///
62/// `resolve` returns `None` for a name this resolver does not claim, which is
63/// not an error: it means no handler owns that placeholder, and the include is
64/// dropped so the page renders without it. That matches what a client does with
65/// an unresolved include, so a missing handler looks the same whichever side
66/// notices it.
67pub trait IncludeResolver: Send + Sync {
68    fn resolve(&self, name: &str, request: &IncludeRequest<'_>) -> Option<Vec<Token>>;
69}
70
71/// The `name` attribute of an `[include]` open tag, if it has one.
72fn include_name(attributes: &[dustnet_core::scanner::Attribute]) -> Option<&str> {
73    attributes
74        .iter()
75        .find(|attribute| attribute.name == NAME_ATTR)
76        .map(|attribute| match &attribute.value {
77            dustnet_core::scanner::AttributeValue::String(value)
78            | dustnet_core::scanner::AttributeValue::Ident(value) => value.as_str(),
79            dustnet_core::scanner::AttributeValue::Flag => "",
80        })
81        .filter(|name| !name.is_empty())
82}
83
84/// Whether a token is an `[include]` tag of either kind.
85fn is_include(token: &Token) -> bool {
86    match token {
87        Token::OpenTag { name, .. } | Token::CloseTag { name } => name == INCLUDE_TAG,
88        _ => false,
89    }
90}
91
92/// Replace every `[include]` in `content` with what `resolver` provides.
93///
94/// Returns `content` untouched when it names no includes. That is not only an
95/// optimisation: an authored page is trusted input, and re-encoding one that
96/// needs no substitution would risk changing it for no reason.
97///
98/// A `[/include]` is dropped alongside its opening tag. The parser treats
99/// `[include]` as self-closing, so a closing tag is already meaningless; leaving
100/// it in the output would surface as a stray close tag on the client.
101pub fn resolve_page(
102    content: &str,
103    resolver: &dyn IncludeResolver,
104    request: &IncludeRequest<'_>,
105) -> Result<String, ProtocolError> {
106    if !content.contains("[include") {
107        return Ok(content.to_string());
108    }
109
110    let mut scanner = Scanner::new(content.as_bytes())
111        .map_err(|_| ProtocolError::InvalidMessage("page is not scannable AML".into()))?;
112    let tokens = scanner
113        .scan_all()
114        .map_err(|_| ProtocolError::InvalidMessage("page is not scannable AML".into()))?;
115
116    let mut resolved: Vec<Token> = Vec::new();
117    for token in &tokens {
118        match token {
119            Token::OpenTag {
120                name, attributes, ..
121            } if name == INCLUDE_TAG => {
122                let Some(include) = include_name(attributes) else {
123                    // A nameless include names no handler, so nothing can claim
124                    // it. `dustnet check` reports it as E011; serving drops it
125                    // rather than refusing the whole page over one placeholder.
126                    continue;
127                };
128                let Some(generated) = resolver.resolve(include, request) else {
129                    continue;
130                };
131                if generated.iter().any(is_include) {
132                    return Err(ProtocolError::InvalidMessage(
133                        "resolver returned an [include]; resolution is a single pass".into(),
134                    ));
135                }
136                resolved.extend(generated);
137            }
138            Token::CloseTag { name } if name == INCLUDE_TAG => continue,
139            other => resolved.push(other.clone()),
140        }
141    }
142
143    to_aml(&resolved)
144        .map_err(|error| ProtocolError::InvalidMessage(format!("generated AML: {error}").into()))
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150    use dustnet_core::scanner::{Attribute, AttributeValue};
151
152    /// A resolver built from a list of `(name, tokens)` pairs.
153    struct Fixed(Vec<(&'static str, Vec<Token>)>);
154
155    impl IncludeResolver for Fixed {
156        fn resolve(&self, name: &str, _request: &IncludeRequest<'_>) -> Option<Vec<Token>> {
157            self.0
158                .iter()
159                .find(|(claimed, _)| *claimed == name)
160                .map(|(_, tokens)| tokens.clone())
161        }
162    }
163
164    fn text(body: &str) -> Vec<Token> {
165        vec![
166            Token::OpenTag {
167                name: "text".into(),
168                attributes: Vec::new(),
169                self_closing: false,
170            },
171            Token::Text(body.into()),
172            Token::CloseTag {
173                name: "text".into(),
174            },
175        ]
176    }
177
178    fn request() -> IncludeRequest<'static> {
179        IncludeRequest {
180            path: "/index.aml",
181            query: None,
182            identity: None,
183        }
184    }
185
186    fn resolve(content: &str, resolver: &dyn IncludeResolver) -> String {
187        resolve_page(content, resolver, &request()).expect("resolution failed")
188    }
189
190    #[test]
191    fn substitutes_a_claimed_include() {
192        let resolver = Fixed(vec![("links", text("a story"))]);
193        let out = resolve(
194            r#"[page mode=document][include name="links" /][/page]"#,
195            &resolver,
196        );
197        assert!(out.contains("a story"), "{out}");
198        assert!(!out.contains("include"), "{out}");
199    }
200
201    /// An unclaimed name is not an error. The page serves without it, which is
202    /// what the client would do with the include anyway.
203    #[test]
204    fn drops_an_unclaimed_include() {
205        let resolver = Fixed(Vec::new());
206        let out = resolve(
207            r#"[page mode=document][text]before[/text][include name="links" /][/page]"#,
208            &resolver,
209        );
210        assert!(out.contains("before"), "{out}");
211        assert!(!out.contains("include"), "{out}");
212        assert!(!out.contains("links"), "{out}");
213    }
214
215    /// A page with no includes is returned byte-for-byte. Authored AML is
216    /// trusted and there is no reason to re-encode it.
217    #[test]
218    fn leaves_a_page_without_includes_untouched() {
219        let source = r#"[page mode=document][text fg=red]x[/text][/page]"#;
220        let out = resolve(source, &Fixed(Vec::new()));
221        assert_eq!(out, source);
222    }
223
224    /// The property the whole design exists for: a resolver returning
225    /// user-submitted text that looks like markup produces text, not markup.
226    #[test]
227    fn generated_user_text_cannot_become_markup() {
228        let hostile = r#"x" ][form action="/login"][input name="password" password /][/form]"#;
229        let resolver = Fixed(vec![("links", text(hostile))]);
230        let out = resolve(
231            r#"[page mode=document][include name="links" /][/page]"#,
232            &resolver,
233        );
234
235        // Scan what we would put on the wire and confirm no form appeared.
236        let tokens = Scanner::new(out.as_bytes())
237            .expect("output is scannable")
238            .scan_all()
239            .expect("output scans");
240        assert!(
241            !tokens.iter().any(|token| matches!(
242                token,
243                Token::OpenTag { name, .. } if name == "form" || name == "input"
244            )),
245            "injected markup became elements: {out}"
246        );
247        // And the hostile string is still there, as text.
248        assert!(tokens.iter().any(
249            |token| matches!(token, Token::Text(body) if body.contains(r#"[form action="/login"]"#))
250        ));
251    }
252
253    /// A hostile *attribute* value, which is the shape the prototype's raw URL
254    /// interpolation actually got wrong.
255    #[test]
256    fn generated_attribute_values_cannot_close_their_quote() {
257        let hostile = r#"https://ok.example/" ][form action="/login"]"#;
258        let resolver = Fixed(vec![(
259            "links",
260            vec![Token::OpenTag {
261                name: "link".into(),
262                attributes: vec![Attribute {
263                    name: "href".into(),
264                    value: AttributeValue::String(hostile.into()),
265                }],
266                self_closing: true,
267            }],
268        )]);
269        let out = resolve(
270            r#"[page mode=document][include name="links" /][/page]"#,
271            &resolver,
272        );
273        let tokens = Scanner::new(out.as_bytes())
274            .expect("output is scannable")
275            .scan_all()
276            .expect("output scans");
277        assert!(
278            !tokens.iter().any(|token| matches!(
279                token,
280                Token::OpenTag { name, .. } if name == "form"
281            )),
282            "attribute escaped its quote: {out}"
283        );
284    }
285
286    /// Resolution is a single pass, so a resolver cannot make the server loop
287    /// by returning another placeholder.
288    #[test]
289    fn a_resolver_returning_an_include_is_refused() {
290        let resolver = Fixed(vec![(
291            "links",
292            vec![Token::OpenTag {
293                name: "include".into(),
294                attributes: vec![Attribute {
295                    name: "name".into(),
296                    value: AttributeValue::String("links".into()),
297                }],
298                self_closing: true,
299            }],
300        )]);
301        let error = resolve_page(
302            r#"[page mode=document][include name="links" /][/page]"#,
303            &resolver,
304            &request(),
305        )
306        .expect_err("expected refusal");
307        assert!(format!("{error}").contains("single pass"), "{error}");
308    }
309
310    #[test]
311    fn a_nameless_include_is_dropped() {
312        let out = resolve("[page mode=document][include /][/page]", &Fixed(Vec::new()));
313        assert!(!out.contains("include"), "{out}");
314    }
315
316    /// Several placeholders on one page, each claimed by a different name, and
317    /// resolved in source order.
318    #[test]
319    fn resolves_every_placeholder_independently() {
320        let resolver = Fixed(vec![("account", text("log in")), ("links", text("story"))]);
321        let out = resolve(
322            r#"[page mode=document][include name="account" /][include name="links" /][/page]"#,
323            &resolver,
324        );
325        let account = out.find("log in").expect("account content missing");
326        let links = out.find("story").expect("links content missing");
327        assert!(account < links, "resolved out of source order: {out}");
328    }
329
330    /// A closing tag is dropped with its opener rather than left to surface as
331    /// a stray close tag on the client.
332    #[test]
333    fn a_closing_include_tag_is_dropped_too() {
334        let resolver = Fixed(vec![("links", text("story"))]);
335        let out = resolve(
336            r#"[page mode=document][include name="links"][/include][/page]"#,
337            &resolver,
338        );
339        assert!(out.contains("story"), "{out}");
340        assert!(!out.contains("include"), "{out}");
341    }
342}