pimconf 0.1.0

CLI and lib to discover PIM-related services
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

//! # Mozilla autoconfig `mailconf=<URL>` TXT discovery coroutine
//!
//! [`DiscoveryMailconf`] wraps the shared [`DiscoveryDnsTxt`]
//! coroutine to query TXT records for a domain and locate one
//! prefixed with `mailconf=`. Per the Mozilla
//! [Autoconfiguration] convention, that prefix introduces a URL
//! pointing at an autoconfig XML document.
//!
//! Per RFC 1035 §3.3.14 a TXT record is a sequence of length-prefixed
//! character-strings. Long values may be split across multiple
//! character-strings; the coroutine concatenates them (no separator,
//! per RFC 6376 §3.6.2.2 / RFC 7208 §3.3) before checking the prefix.
//!
//! Per-record failures (missing `mailconf=` prefix, non-UTF-8 value,
//! malformed URL) are skipped silently: the coroutine only fails if
//! no record at the queried name yields a valid URL.
//!
//! [Autoconfiguration]: https://wiki.mozilla.org/Thunderbird:Autoconfiguration

use core::str;

use alloc::{string::ToString, vec::Vec};

use log::trace;
use thiserror::Error;
use url::Url;

use crate::{
    coroutine::{DiscoveryCoroutine, DiscoveryCoroutineState, DiscoveryYield},
    shared::dns::{DiscoveryDnsTxt, DiscoveryDnsTxtError},
};

/// Errors that can occur during a single mailconf discovery.
#[derive(Debug, Error)]
pub enum DiscoveryMailconfError {
    #[error(transparent)]
    Dns(#[from] DiscoveryDnsTxtError),
    #[error("no `mailconf=` TXT record found for the queried domain")]
    NoMailconfRecord,
}

/// I/O-free coroutine that performs a TXT lookup and extracts the
/// first valid `mailconf=<URL>` value.
pub struct DiscoveryMailconf {
    txt: DiscoveryDnsTxt,
}

impl DiscoveryMailconf {
    /// Returns a coroutine ready to query `domain` for TXT records on
    /// the first [`resume`]. `resolver` must be a `tcp://host:port`
    /// URL pointing at a DNS-over-TCP resolver.
    ///
    /// [`resume`]: DiscoveryMailconf::resume
    pub fn new(domain: impl ToString, resolver: Url) -> Self {
        Self {
            txt: DiscoveryDnsTxt::new(domain, resolver),
        }
    }
}

impl DiscoveryCoroutine for DiscoveryMailconf {
    type Yield = DiscoveryYield;
    type Return = Result<Url, DiscoveryMailconfError>;

    fn resume(&mut self, arg: Option<&[u8]>) -> DiscoveryCoroutineState<Self::Yield, Self::Return> {
        match self.txt.resume(arg) {
            DiscoveryCoroutineState::Yielded(y) => DiscoveryCoroutineState::Yielded(y),
            DiscoveryCoroutineState::Complete(Err(err)) => {
                DiscoveryCoroutineState::Complete(Err(err.into()))
            }
            DiscoveryCoroutineState::Complete(Ok(records)) => {
                for record in records {
                    let mut joined = Vec::new();

                    for cs in record.rdata.iter() {
                        joined.extend_from_slice(&cs.octets);
                    }

                    let Some(value) = joined.strip_prefix(b"mailconf=") else {
                        trace!("no `mailconf=` prefix in TXT record, skip");
                        continue;
                    };

                    let Ok(url_str) = str::from_utf8(value) else {
                        trace!("`mailconf=` TXT value is not valid UTF-8, skip");
                        continue;
                    };

                    let Ok(url) = Url::parse(url_str.trim()) else {
                        trace!("`mailconf=` TXT value `{url_str}` is not a valid URL, skip");
                        continue;
                    };

                    return DiscoveryCoroutineState::Complete(Ok(url));
                }

                DiscoveryCoroutineState::Complete(Err(DiscoveryMailconfError::NoMailconfRecord))
            }
        }
    }
}