dustnet_server/input.rs
1//! Accepting form submissions.
2//!
3//! Without a handler the server refuses `INPUT` with 405, which is what it did
4//! before this module existed and what `dustnetd` still does. Installing a
5//! handler is what lets a site accept a submission.
6//!
7//! # Fields are ordered and duplicates are kept
8//!
9//! [`docs/spec/02-protocol.md`](../../../docs/spec/02-protocol.md) says of the
10//! INPUT body: "Repeated field names are permitted and retain document order."
11//! So [`FormFields`] is a `Vec`, not a map. Collapsing duplicates would quietly
12//! discard data and, worse, make *which* value survives depend on whether the
13//! implementation kept the first or the last — a difference an attacker picks
14//! and a reviewer does not see.
15//!
16//! # What a handler is told, and what it returns
17//!
18//! A handler gets the path, any query riding on the form's action, and the
19//! fields. It returns [`InputOutcome`] — which page to answer with, or a
20//! refusal — and **never markup**. Rendering goes through the include resolver
21//! either way, so there is exactly one place that generates a page and it
22//! behaves the same whether or not a submission preceded it.
23//!
24//! An accepted submission is answered with the target *page*, not a redirect.
25//! That is forced by the protocol rather than chosen: `validate_redirect_body`
26//! requires an absolute `atp://` target, because the client resolves it with
27//! `AtpUri::parse` rather than against the current URI — and a server does not
28//! know its own public hostname, only the address it happens to be bound to.
29//! Answering with the page is what
30//! [`docs/spec/02-protocol.md`](../../../docs/spec/02-protocol.md) permits
31//! ("The server responds with a PAGE, REDIRECT, or ERROR") and costs one round
32//! trip instead of two.
33
34/// Most fields one submission may carry.
35///
36/// The body is already bounded by `MAX_INPUT_MESSAGE_SIZE`, but a bounded body
37/// can still hold a great many `&`s. This bounds the parsed vector too, so the
38/// cost of a submission is bounded in both bytes and elements.
39const MAX_FIELDS: usize = 64;
40
41/// Longest refusal reason that reaches the client.
42///
43/// A reason is a sentence for a person to read, and the client has to lay it
44/// out. A handler that puts a transport diagnostic in one — a multi-line SMTP
45/// error with a support URL, say — produced a page the client refused to render
46/// at all, reporting "page exceeded client resource budget" and hiding the
47/// actual problem. Bounding it here means no handler can do that, rather than
48/// every handler having to remember not to.
49pub(crate) const MAX_REASON: usize = 200;
50
51/// The decoded fields of one submission, in the order they were sent.
52#[derive(Debug, Default, Clone)]
53pub struct FormFields {
54 fields: Vec<(String, String)>,
55}
56
57impl FormFields {
58 /// Decode `key=value&key2=value2`, as the reference client encodes it:
59 /// `+` for a space and `%XX` for anything else outside the unreserved set.
60 ///
61 /// Malformed input is decoded as far as it makes sense rather than
62 /// rejected: a stray `%` is kept literally, and a pair with no `=` becomes
63 /// a field with an empty value. A submission is not a place to be clever —
64 /// the handler decides what it requires, and every value is untrusted
65 /// either way.
66 pub fn parse(encoded: &str) -> Self {
67 let mut fields = Vec::new();
68 for pair in encoded.split('&') {
69 if pair.is_empty() || fields.len() >= MAX_FIELDS {
70 continue;
71 }
72 let (name, value) = match pair.split_once('=') {
73 Some((name, value)) => (name, value),
74 None => (pair, ""),
75 };
76 fields.push((decode(name), decode(value)));
77 }
78 Self { fields }
79 }
80
81 /// The first value sent under `name`.
82 ///
83 /// First rather than last, and stated here because the choice is only
84 /// invisible until two values disagree. A handler that cares which one it
85 /// got should use [`FormFields::all`] and decide deliberately.
86 pub fn get(&self, name: &str) -> Option<&str> {
87 self.fields
88 .iter()
89 .find(|(field, _)| field == name)
90 .map(|(_, value)| value.as_str())
91 }
92
93 /// Every value sent under `name`, in order.
94 pub fn all<'a>(&'a self, name: &'a str) -> impl Iterator<Item = &'a str> + 'a {
95 self.fields
96 .iter()
97 .filter(move |(field, _)| field == name)
98 .map(|(_, value)| value.as_str())
99 }
100
101 pub fn len(&self) -> usize {
102 self.fields.len()
103 }
104
105 pub fn is_empty(&self) -> bool {
106 self.fields.is_empty()
107 }
108}
109
110/// Percent-decode one form component, treating `+` as a space.
111///
112/// Builds bytes and then converts, so a multi-byte character split across
113/// several `%XX` escapes reassembles. Invalid UTF-8 becomes U+FFFD rather than
114/// an error: the field is untrusted text either way, and a replacement
115/// character is a better answer than refusing a whole submission.
116fn decode(value: &str) -> String {
117 let bytes = value.as_bytes();
118 let mut out: Vec<u8> = Vec::with_capacity(bytes.len());
119 let mut index = 0;
120 // Indexed with `get` throughout: the crate denies `clippy::indexing_slicing`
121 // because this is a parser over remote bytes, and "the bound is obvious
122 // from the loop condition" is exactly the reasoning that goes stale when
123 // someone edits the loop.
124 while let Some(&byte) = bytes.get(index) {
125 match byte {
126 b'+' => {
127 out.push(b' ');
128 index += 1;
129 }
130 b'%' => {
131 let pair = bytes
132 .get(index + 1..index + 3)
133 .and_then(|pair| std::str::from_utf8(pair).ok())
134 .and_then(|pair| u8::from_str_radix(pair, 16).ok());
135 match pair {
136 Some(decoded) => {
137 out.push(decoded);
138 index += 3;
139 }
140 // Truncated, or not hex: not an escape, so keep the `%`.
141 None => {
142 out.push(b'%');
143 index += 1;
144 }
145 }
146 }
147 other => {
148 out.push(other);
149 index += 1;
150 }
151 }
152 }
153 String::from_utf8_lossy(&out).into_owned()
154}
155
156/// What a handler is told about a submission.
157#[derive(Debug, Clone, Copy)]
158pub struct InputRequest<'a> {
159 /// The form's action path, with any query removed.
160 pub path: &'a str,
161 /// The query the action carried, if any — how a form says *which* thing it
162 /// acts on, as in `[form action="/index?reply=12"]`.
163 pub query: Option<&'a str>,
164 /// The submitted fields.
165 pub fields: &'a FormFields,
166 /// Who submitted, resolved from their session token, or `None` for
167 /// anonymous. Never the token itself — see [`crate::session`].
168 pub identity: Option<&'a str>,
169 /// Where the submission came from.
170 ///
171 /// Given here and not to the include resolver, because this is what abuse
172 /// control needs and rendering does not: a login endpoint that cannot count
173 /// attempts per source cannot be defended against guessing, and a global
174 /// counter would let one attacker lock out everybody.
175 pub peer: std::net::IpAddr,
176}
177
178/// A handler's answer to a submission.
179#[derive(Debug, Clone)]
180pub enum InputOutcome {
181 /// Accepted. The server answers with this page, rendered exactly as a GET
182 /// for it would be — same include resolution, same everything — so there is
183 /// one path that produces a page whether or not a submission preceded it.
184 Render {
185 path: String,
186 query: Option<String>,
187 /// Session changes to apply to the response — issuing a token on a
188 /// successful login, clearing one on logout. Part of the return value
189 /// rather than a side effect, so a handler that grants a session says
190 /// so in the value it hands back.
191 session: crate::session::SessionChange,
192 },
193 /// Refused, with a reason to show the person who submitted it.
194 ///
195 /// A short sentence for a person to read. Anything longer is truncated
196 /// before it reaches the wire — see [`MAX_REASON`].
197 Rejected(String),
198}
199
200impl InputOutcome {
201 /// Accept, and answer with `path` and no query.
202 pub fn render(path: impl Into<String>) -> Self {
203 Self::Render {
204 path: path.into(),
205 query: None,
206 session: crate::session::SessionChange::none(),
207 }
208 }
209
210 /// Accept, and answer with `path?query`.
211 pub fn render_query(path: impl Into<String>, query: impl Into<String>) -> Self {
212 Self::Render {
213 path: path.into(),
214 query: Some(query.into()),
215 session: crate::session::SessionChange::none(),
216 }
217 }
218
219 /// Attach session changes to an acceptance.
220 ///
221 /// A no-op on a refusal: a refused login must not issue a session, and
222 /// making that unrepresentable is better than trusting every caller to
223 /// remember it.
224 pub fn with_session(self, change: crate::session::SessionChange) -> Self {
225 match self {
226 Self::Render { path, query, .. } => Self::Render {
227 path,
228 query,
229 session: change,
230 },
231 rejected @ Self::Rejected(_) => rejected,
232 }
233 }
234}
235
236/// Handles form submissions for a site.
237pub trait InputHandler: Send + Sync {
238 fn handle(&self, request: &InputRequest<'_>) -> InputOutcome;
239}
240
241/// Trim a refusal reason to something a client can render.
242///
243/// Truncated on a character boundary, and marked so the reader can tell they are
244/// seeing part of a sentence rather than a badly-worded whole one.
245pub(crate) fn short_reason(reason: &str) -> String {
246 if reason.chars().count() <= MAX_REASON {
247 return reason.to_string();
248 }
249 let kept: String = reason.chars().take(MAX_REASON - 1).collect();
250 format!("{kept}…")
251}
252
253/// Split a form action into its path and query.
254pub(crate) fn split_query(action: &str) -> (&str, Option<&str>) {
255 match action.split_once('?') {
256 Some((path, query)) if !query.is_empty() => (path, Some(query)),
257 Some((path, _)) => (path, None),
258 None => (action, None),
259 }
260}
261
262#[cfg(test)]
263mod tests {
264 use super::*;
265
266 #[test]
267 fn parses_a_simple_submission() {
268 let fields = FormFields::parse("title=Hello&url=atp%3A%2F%2Fx.dust");
269 assert_eq!(fields.get("title"), Some("Hello"));
270 assert_eq!(fields.get("url"), Some("atp://x.dust"));
271 assert_eq!(fields.len(), 2);
272 }
273
274 #[test]
275 fn plus_is_a_space() {
276 let fields = FormFields::parse("q=hello+world");
277 assert_eq!(fields.get("q"), Some("hello world"));
278 }
279
280 /// A multi-byte character arrives as consecutive escapes and must be
281 /// reassembled, not decoded byte by byte into mojibake.
282 #[test]
283 fn multibyte_escapes_reassemble() {
284 let fields = FormFields::parse("t=caf%C3%A9+%E2%98%85");
285 assert_eq!(fields.get("t"), Some("café ★"));
286 }
287
288 /// Order is preserved and duplicates are kept, which the protocol
289 /// specifies. Collapsing them would make which value wins an accident.
290 #[test]
291 fn duplicate_names_are_all_retained_in_order() {
292 let fields = FormFields::parse("tag=a&tag=b&tag=c");
293 assert_eq!(fields.all("tag").collect::<Vec<_>>(), ["a", "b", "c"]);
294 assert_eq!(fields.get("tag"), Some("a"), "get returns the first");
295 }
296
297 #[test]
298 fn malformed_input_decodes_as_far_as_it_can() {
299 let fields = FormFields::parse("bare&a=%zz&b=%&c=x");
300 assert_eq!(fields.get("bare"), Some(""), "no = means empty value");
301 assert_eq!(fields.get("a"), Some("%zz"), "not hex, so not an escape");
302 assert_eq!(fields.get("b"), Some("%"), "truncated escape");
303 assert_eq!(fields.get("c"), Some("x"));
304 }
305
306 /// A bounded body can still carry a great many separators, so the parsed
307 /// vector is bounded too.
308 #[test]
309 fn field_count_is_bounded() {
310 let encoded = (0..MAX_FIELDS * 4)
311 .map(|index| format!("f{index}=v"))
312 .collect::<Vec<_>>()
313 .join("&");
314 assert_eq!(FormFields::parse(&encoded).len(), MAX_FIELDS);
315 }
316
317 #[test]
318 fn an_empty_body_is_no_fields() {
319 assert!(FormFields::parse("").is_empty());
320 }
321
322 /// A form action carries which thing it acts on as a query.
323 /// A handler that puts a transport diagnostic in a refusal must not be able
324 /// to hand the client something it cannot lay out.
325 #[test]
326 fn an_over_long_reason_is_truncated() {
327 let short = "a title is required";
328 assert_eq!(short_reason(short), short);
329
330 // The shape that caused it: a real SMTP 421 with a support URL.
331 let diagnostic = "could not send mail: transient error (421): 4.7.0 Try again \
332 later, closing connection. (EHLO) For more information, go to \
333 https://support.google.com/a/answer/3221692 \
334 5b1f17b1804b1-499c2fb02ecsm5772355e9.4 - gsmtp";
335 let trimmed = short_reason(diagnostic);
336 assert!(trimmed.chars().count() <= MAX_REASON);
337 assert!(trimmed.ends_with('…'), "{trimmed}");
338 }
339
340 /// Truncation must not split a character.
341 #[test]
342 fn truncation_lands_on_a_character_boundary() {
343 let reason = "é".repeat(MAX_REASON * 2);
344 let trimmed = short_reason(&reason);
345 assert!(trimmed.chars().count() <= MAX_REASON);
346 assert!(trimmed.is_char_boundary(trimmed.len()));
347 }
348
349 #[test]
350 fn an_action_query_is_split_off() {
351 assert_eq!(split_query("/index?reply=12"), ("/index", Some("reply=12")));
352 assert_eq!(split_query("/index"), ("/index", None));
353 assert_eq!(split_query("/index?"), ("/index", None));
354 }
355
356 /// A refusal cannot be turned into a session. Attaching one to a rejection
357 /// is silently dropped rather than quietly granting a login that failed.
358 #[test]
359 fn a_refusal_cannot_carry_a_session() {
360 let outcome = InputOutcome::Rejected("nope".into())
361 .with_session(crate::session::SessionChange::set("t", "/", 1));
362 assert!(matches!(outcome, InputOutcome::Rejected(_)));
363 }
364
365 #[test]
366 fn a_session_attaches_to_an_acceptance() {
367 let outcome =
368 InputOutcome::render("/").with_session(crate::session::SessionChange::set("t", "/", 1));
369 match outcome {
370 InputOutcome::Render { session, .. } => assert!(!session.is_empty()),
371 other => panic!("expected Render, got {other:?}"),
372 }
373 }
374
375 #[test]
376 fn outcome_constructors_carry_the_query() {
377 match InputOutcome::render("/index") {
378 InputOutcome::Render { path, query, .. } => {
379 assert_eq!(path, "/index");
380 assert_eq!(query, None);
381 }
382 other => panic!("expected Render, got {other:?}"),
383 }
384 match InputOutcome::render_query("/index", "item=7") {
385 InputOutcome::Render { path, query, .. } => {
386 assert_eq!(path, "/index");
387 assert_eq!(query.as_deref(), Some("item=7"));
388 }
389 other => panic!("expected Render, got {other:?}"),
390 }
391 }
392
393 /// Values are never trusted, and nothing here tries to make them safe:
394 /// escaping is the serializer's job, at the point markup is written.
395 /// This pins that a hostile value survives decoding intact so the handler
396 /// sees exactly what was sent.
397 #[test]
398 fn hostile_values_are_delivered_verbatim() {
399 let hostile = r#"x" ][form action="/login"]"#;
400 let encoded = format!(
401 "title={}",
402 hostile
403 .bytes()
404 .map(|byte| format!("%{byte:02X}"))
405 .collect::<String>()
406 );
407 assert_eq!(FormFields::parse(&encoded).get("title"), Some(hostile));
408 }
409}