mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 22:14:30 +00:00
* craft-mime: strict base64, mailto links and code page labels from MailCraft What MailCraft's mime and charset crates still had that craft-mime did not: strict RFC 4648 base64 (crates/charset), mailto: links (RFC 6068, crates/mime) and the Windows code page to charset label table (crates/pst). With these, MailCraft's charset crate has nothing craft-mime lacks. * Add craft-vcard: vCard reader and writer from MailCraft MailCraft crates/vcard at a44a450: vCard 2.1, 3.0 and 4.0 read, 3.0 written, with its limits and tests. The model is the crate's own Contact (the vCard fields of MailCraft's); the birthday is a chrono::NaiveDate. Character sets and strict base64 come from craft-mime. --------- Co-authored-by: Martin Ball <98639962+benandez@users.noreply.github.com>
327 lines
13 KiB
Rust
327 lines
13 KiB
Rust
//! Writing contacts as vCard 3.0.
|
|
|
|
use crate::Contact;
|
|
use chrono::{Datelike, NaiveDate};
|
|
|
|
use crate::lines::fold;
|
|
use crate::text::{escape, multi, single};
|
|
|
|
/// Write vCard 3.0 cards, CRLF line endings, lines folded at 75 octets on char boundaries.
|
|
///
|
|
/// `FN` is the contact's [`name`](Contact::name). Values are escaped. Every field but the notes is
|
|
/// one line: its line breaks and other control characters become spaces. A label the format has a
|
|
/// `TYPE` for (`work`, `home`, `other`; for phones also `mobile`, `fax`, `pager`) is written as
|
|
/// that type; any other label is written as the `X-ABLabel` of a group (`item1.TEL` +
|
|
/// `item1.X-ABLabel:Car`), which is how address books exchange custom labels. E-mail addresses,
|
|
/// phone numbers, postal addresses and web sites with nothing in them are left out. Keys are
|
|
/// written as `KEY;TYPE=X509;ENCODING=b:` and `KEY;TYPE=PGP;ENCODING=b:`; one that would not read
|
|
/// back as itself is left out, and so is the address of a key, which vCard 3.0 has no form for.
|
|
pub fn write(contacts: &[&Contact]) -> String {
|
|
let mut out = String::new();
|
|
for contact in contacts {
|
|
card(&mut out, contact);
|
|
}
|
|
out
|
|
}
|
|
|
|
/// A one-line field, escaped.
|
|
fn field(s: &str) -> String {
|
|
escape(&single(s))
|
|
}
|
|
|
|
/// `NAME:value` when there is a value.
|
|
fn optional(out: &mut String, name: &str, value: &str) {
|
|
let value = field(value);
|
|
if !value.is_empty() {
|
|
fold(out, &format!("{name}:{value}"));
|
|
}
|
|
}
|
|
|
|
/// The `TYPE` of an e-mail or postal address label, when the format has one for it.
|
|
fn place_type(label: &str) -> Option<&'static str> {
|
|
match label {
|
|
"work" => Some("WORK"),
|
|
"home" => Some("HOME"),
|
|
"other" => Some("OTHER"),
|
|
_ => None,
|
|
}
|
|
}
|
|
|
|
fn phone_type(label: &str) -> Option<&'static str> {
|
|
match label {
|
|
"mobile" => Some("CELL"),
|
|
"fax" => Some("FAX"),
|
|
"pager" => Some("PAGER"),
|
|
_ => place_type(label),
|
|
}
|
|
}
|
|
|
|
/// One labelled property. `kind` is the type the property always has (`INTERNET`), `known` the
|
|
/// type its label stands for; a label without one goes into an `X-ABLabel` of the same group.
|
|
fn labeled(out: &mut String, groups: &mut u32, name: &str, kind: Option<&str>, known: Option<&str>, label: &str, value: &str) {
|
|
let types: Vec<&str> = kind.into_iter().chain(known).collect();
|
|
let params = if types.is_empty() { String::new() } else { format!(";TYPE={}", types.join(",")) };
|
|
let custom = if known.is_some() { String::new() } else { field(label) };
|
|
if custom.is_empty() {
|
|
fold(out, &format!("{name}{params}:{value}"));
|
|
} else {
|
|
*groups = groups.saturating_add(1);
|
|
fold(out, &format!("item{groups}.{name}{params}:{value}"));
|
|
fold(out, &format!("item{groups}.X-ABLabel:{custom}"));
|
|
}
|
|
}
|
|
|
|
fn card(out: &mut String, c: &Contact) {
|
|
fold(out, "BEGIN:VCARD");
|
|
fold(out, "VERSION:3.0");
|
|
fold(out, &format!("N:{};{};{};;", field(&c.last), field(&c.first), field(&c.middle)));
|
|
fold(out, &format!("FN:{}", field(&c.name())));
|
|
optional(out, "NICKNAME", &c.nickname);
|
|
let (company, department) = (field(&c.company), field(&c.department));
|
|
if !department.is_empty() {
|
|
fold(out, &format!("ORG:{company};{department}"));
|
|
} else if !company.is_empty() {
|
|
fold(out, &format!("ORG:{company}"));
|
|
}
|
|
optional(out, "TITLE", &c.title);
|
|
let mut groups = 0u32;
|
|
for email in &c.emails {
|
|
let value = field(&email.value);
|
|
if !value.is_empty() {
|
|
labeled(out, &mut groups, "EMAIL", Some("INTERNET"), place_type(&email.label), &email.label, &value);
|
|
}
|
|
}
|
|
for phone in &c.phones {
|
|
let value = field(&phone.value);
|
|
if !value.is_empty() {
|
|
labeled(out, &mut groups, "TEL", None, phone_type(&phone.label), &phone.label, &value);
|
|
}
|
|
}
|
|
for address in c.addresses.iter().filter(|a| !a.is_empty()) {
|
|
// Post office box and extended address stay empty: the model keeps them in the street.
|
|
let value = format!(
|
|
";;{};{};{};{};{}",
|
|
field(&address.street),
|
|
field(&address.city),
|
|
field(&address.region),
|
|
field(&address.postal_code),
|
|
field(&address.country)
|
|
);
|
|
labeled(out, &mut groups, "ADR", None, place_type(&address.label), &address.label, &value);
|
|
}
|
|
for site in &c.websites {
|
|
optional(out, "URL", site);
|
|
}
|
|
if let Some(day) = c.birthday {
|
|
// A date that exists, whatever the fields say.
|
|
// A year a card can say (1 to 9999), whatever the date's is.
|
|
let year = day.year().clamp(1, 9999);
|
|
let day = day.with_year(year).or_else(|| NaiveDate::from_ymd_opt(year, day.month(), 28)).unwrap_or_default();
|
|
fold(out, &format!("BDAY:{}", day.format("%Y-%m-%d")));
|
|
}
|
|
let notes = escape(&multi(&c.notes));
|
|
if !notes.is_empty() {
|
|
fold(out, &format!("NOTE:{notes}"));
|
|
}
|
|
let categories: Vec<String> = c.categories.iter().map(|name| field(name)).filter(|name| !name.is_empty()).collect();
|
|
if !categories.is_empty() {
|
|
fold(out, &format!("CATEGORIES:{}", categories.join(",")));
|
|
}
|
|
for key in c.keys.iter().filter_map(crate::key::line).take(Contact::MAX_KEYS) {
|
|
fold(out, &key);
|
|
}
|
|
optional(out, "UID", &c.uid);
|
|
if c.favorite {
|
|
fold(out, "X-MAILCRAFT-FAVORITE:TRUE");
|
|
}
|
|
fold(out, "END:VCARD");
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use crate::{Labeled, PostalAddress};
|
|
|
|
use super::*;
|
|
|
|
fn lines(c: &Contact) -> Vec<String> {
|
|
let out = write(&[c]);
|
|
assert!(out.ends_with("END:VCARD\r\n"));
|
|
let mut cursor = crate::lines::Lines::new(&out);
|
|
std::iter::from_fn(|| cursor.next_line(false)).collect()
|
|
}
|
|
|
|
fn nadia() -> Contact {
|
|
Contact {
|
|
display_name: "Dr. Nadia Okafor".into(),
|
|
first: "Nadia".into(),
|
|
middle: "Chidi".into(),
|
|
last: "Okafor".into(),
|
|
nickname: "Nadi".into(),
|
|
company: "Example Research, Inc.".into(),
|
|
title: "Lead Scientist; Field".into(),
|
|
department: "Field Lab".into(),
|
|
emails: vec![
|
|
Labeled::new("work", "nadia.okafor@example.org"),
|
|
Labeled::new("", "nadia@example.org"),
|
|
Labeled::new("Family", "nadia@family.example.org"),
|
|
Labeled::new("home", " "),
|
|
],
|
|
phones: vec![
|
|
Labeled::new("mobile", "+1 (555) 010-0142"),
|
|
Labeled::new("fax", "+1 555 010 0144"),
|
|
Labeled::new("Car, old", "+1 555 010 0145"),
|
|
Labeled::new("", "+1 555 010 0146"),
|
|
],
|
|
addresses: vec![
|
|
PostalAddress {
|
|
label: "work".into(),
|
|
street: "Suite 300, 41 Harbor Road".into(),
|
|
city: "Riverton".into(),
|
|
region: "CA".into(),
|
|
postal_code: "94000".into(),
|
|
country: "USA".into(),
|
|
},
|
|
PostalAddress { label: "home".into(), ..Default::default() },
|
|
PostalAddress { label: "Cabin".into(), city: "Pinewood".into(), ..Default::default() },
|
|
],
|
|
websites: vec!["https://example.org/~nadia".into(), "".into()],
|
|
birthday: NaiveDate::from_ymd_opt(1985, 4, 12),
|
|
notes: "Met at the 2024 symposium.\r\nPrefers e-mail, not calls.".into(),
|
|
categories: vec!["Research".into(), "Field Team, West".into(), " ".into()],
|
|
favorite: true,
|
|
uid: "7f1c2f6e-0001-4a5b-9c3d-000000000042".into(),
|
|
..Default::default()
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn writes_a_whole_card() {
|
|
assert_eq!(
|
|
lines(&nadia()),
|
|
[
|
|
"BEGIN:VCARD",
|
|
"VERSION:3.0",
|
|
"N:Okafor;Nadia;Chidi;;",
|
|
"FN:Dr. Nadia Okafor",
|
|
"NICKNAME:Nadi",
|
|
"ORG:Example Research\\, Inc.;Field Lab",
|
|
"TITLE:Lead Scientist\\; Field",
|
|
"EMAIL;TYPE=INTERNET,WORK:nadia.okafor@example.org",
|
|
"EMAIL;TYPE=INTERNET:nadia@example.org",
|
|
"item1.EMAIL;TYPE=INTERNET:nadia@family.example.org",
|
|
"item1.X-ABLabel:Family",
|
|
"TEL;TYPE=CELL:+1 (555) 010-0142",
|
|
"TEL;TYPE=FAX:+1 555 010 0144",
|
|
"item2.TEL:+1 555 010 0145",
|
|
"item2.X-ABLabel:Car\\, old",
|
|
"TEL:+1 555 010 0146",
|
|
"ADR;TYPE=WORK:;;Suite 300\\, 41 Harbor Road;Riverton;CA;94000;USA",
|
|
"item3.ADR:;;;Pinewood;;;",
|
|
"item3.X-ABLabel:Cabin",
|
|
"URL:https://example.org/~nadia",
|
|
"BDAY:1985-04-12",
|
|
"NOTE:Met at the 2024 symposium.\\nPrefers e-mail\\, not calls.",
|
|
"CATEGORIES:Research,Field Team\\, West",
|
|
"UID:7f1c2f6e-0001-4a5b-9c3d-000000000042",
|
|
"X-MAILCRAFT-FAVORITE:TRUE",
|
|
"END:VCARD",
|
|
]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn an_empty_contact_is_still_a_card() {
|
|
assert_eq!(write(&[&Contact::default()]), "BEGIN:VCARD\r\nVERSION:3.0\r\nN:;;;;\r\nFN:\r\nEND:VCARD\r\n");
|
|
assert_eq!(write(&[]), "");
|
|
}
|
|
|
|
#[test]
|
|
fn the_formatted_name_falls_back_as_the_model_does() {
|
|
let named = Contact { first: "Ada".into(), last: "Lovelace".into(), ..Default::default() };
|
|
assert!(lines(&named).contains(&"FN:Ada Lovelace".to_string()));
|
|
let company = Contact { company: "Analytical Engines Ltd".into(), ..Default::default() };
|
|
assert_eq!(lines(&company).get(2..5).unwrap(), ["N:;;;;", "FN:Analytical Engines Ltd", "ORG:Analytical Engines Ltd"]);
|
|
let mail = Contact { emails: vec![Labeled::new("home", "x@example.org")], department: "Only a department".into(), ..Default::default() };
|
|
assert_eq!(lines(&mail).get(3..6).unwrap(), ["FN:x@example.org", "ORG:;Only a department", "EMAIL;TYPE=INTERNET,HOME:x@example.org"]);
|
|
}
|
|
|
|
#[test]
|
|
fn every_known_label_is_a_type() {
|
|
let c = Contact {
|
|
emails: ["work", "home", "other", "mobile", "Work"].map(|l| Labeled::new(l, "a@example.org")).to_vec(),
|
|
phones: ["mobile", "work", "home", "fax", "pager", "other", "HOME"].map(|l| Labeled::new(l, "1")).to_vec(),
|
|
..Default::default()
|
|
};
|
|
let got = lines(&c);
|
|
assert_eq!(
|
|
got.get(4..20).unwrap(),
|
|
[
|
|
"EMAIL;TYPE=INTERNET,WORK:a@example.org",
|
|
"EMAIL;TYPE=INTERNET,HOME:a@example.org",
|
|
"EMAIL;TYPE=INTERNET,OTHER:a@example.org",
|
|
"item1.EMAIL;TYPE=INTERNET:a@example.org",
|
|
"item1.X-ABLabel:mobile",
|
|
"item2.EMAIL;TYPE=INTERNET:a@example.org",
|
|
"item2.X-ABLabel:Work",
|
|
"TEL;TYPE=CELL:1",
|
|
"TEL;TYPE=WORK:1",
|
|
"TEL;TYPE=HOME:1",
|
|
"TEL;TYPE=FAX:1",
|
|
"TEL;TYPE=PAGER:1",
|
|
"TEL;TYPE=OTHER:1",
|
|
"item3.TEL:1",
|
|
"item3.X-ABLabel:HOME",
|
|
"END:VCARD",
|
|
]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn lines_end_in_crlf_and_stay_within_75_octets() {
|
|
let mut c = nadia();
|
|
c.notes = "Ünïcödé — 東京 🎉 ".repeat(60);
|
|
c.display_name = "é".repeat(200);
|
|
let out = write(&[&c, &c]);
|
|
assert_eq!(out.matches("BEGIN:VCARD\r\n").count(), 2);
|
|
assert!(!out.replace("\r\n", "").contains(['\r', '\n']));
|
|
assert!(out.split("\r\n").all(|line| line.len() <= 75), "{out}");
|
|
assert!(out.contains("\r\n "));
|
|
}
|
|
|
|
#[test]
|
|
fn text_cannot_inject_lines() {
|
|
let c = Contact {
|
|
display_name: "Ada\r\nEND:VCARD\r\nBEGIN:VCARD".into(),
|
|
first: "A\nTEL:666".into(),
|
|
nickname: "x\rEMAIL:evil@example.org".into(),
|
|
emails: vec![Labeled::new("work\r\nTEL:1", "a@example.org\r\nTEL:2")],
|
|
notes: "one\r\nEND:VCARD\rtwo\u{0}".into(),
|
|
categories: vec!["a\nb".into()],
|
|
uid: "u\nUID:2".into(),
|
|
..Default::default()
|
|
};
|
|
let got = lines(&c);
|
|
assert_eq!(got.iter().filter(|l| l.starts_with("BEGIN:") || l.starts_with("END:")).count(), 2, "{got:?}");
|
|
assert!(!got.iter().any(|l| l.starts_with("TEL")), "{got:?}");
|
|
assert_eq!(got.iter().filter(|l| l.starts_with("UID") || l.contains("EMAIL")).count(), 3, "{got:?}");
|
|
assert!(got.contains(&"FN:Ada END:VCARD BEGIN:VCARD".to_string()));
|
|
assert!(got.contains(&"NOTE:one\\nEND:VCARD\\ntwo".to_string()));
|
|
assert!(got.contains(&"item1.X-ABLabel:work TEL:1".to_string()));
|
|
}
|
|
|
|
#[test]
|
|
fn hostile_birthdays_are_written_as_real_dates() {
|
|
for hostile in [
|
|
NaiveDate::MIN,
|
|
NaiveDate::MAX,
|
|
NaiveDate::from_ymd_opt(0, 1, 1).unwrap(),
|
|
NaiveDate::from_ymd_opt(-4, 2, 29).unwrap(),
|
|
NaiveDate::from_ymd_opt(10_000, 2, 29).unwrap(),
|
|
] {
|
|
let c = Contact { birthday: Some(hostile), ..Default::default() };
|
|
let back = crate::parse(&write(&[&c]));
|
|
assert!(back[0].birthday.is_some(), "{hostile:?}");
|
|
}
|
|
}
|
|
}
|