xmpp_parsers/
jingle_ft.rs

1// Copyright (c) 2017 Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7use xso::{error::Error, AsXml, FromXml};
8
9use crate::date::DateTime;
10use crate::hashes::Hash;
11use crate::jingle::{ContentId, Creator};
12use crate::ns;
13use alloc::collections::btree_map::BTreeMap;
14use core::str::FromStr;
15
16/// Represents a range in a file.
17#[derive(FromXml, AsXml, PartialEq, Debug, Clone, Default)]
18#[xml(namespace = ns::JINGLE_FT, name = "range")]
19pub struct Range {
20    /// The offset in bytes from the beginning of the file.
21    #[xml(attribute(default))]
22    pub offset: u64,
23
24    /// The length in bytes of the range, or None to be the entire
25    /// remaining of the file.
26    #[xml(attribute(default))]
27    pub length: Option<u64>,
28
29    /// List of hashes for this range.
30    #[xml(child(n = ..))]
31    pub hashes: Vec<Hash>,
32}
33
34impl Range {
35    /// Creates a new range.
36    pub fn new() -> Range {
37        Default::default()
38    }
39}
40
41type Lang = String;
42
43/// Represents a file to be transferred.
44#[derive(FromXml, AsXml, Debug, Clone, Default)]
45#[xml(namespace = ns::JINGLE_FT, name = "file")]
46pub struct File {
47    /// The date of last modification of this file.
48    #[xml(extract(default, fields(text(type_ = DateTime))))]
49    pub date: Option<DateTime>,
50
51    /// The MIME type of this file.
52    #[xml(extract(default, name = "media-type", fields(text(type_ = String))))]
53    pub media_type: Option<String>,
54
55    /// The name of this file.
56    #[xml(extract(default, fields(text(type_ = String))))]
57    pub name: Option<String>,
58
59    /// The description of this file, possibly localised.
60    #[xml(extract(n = .., name = "desc", fields(
61        attribute(name = "xml:lang", type_ = String),
62        text(type_ = String)
63    )))]
64    pub descs: BTreeMap<Lang, String>,
65
66    /// The size of this file, in bytes.
67    #[xml(extract(default, fields(text(type_ = u64))))]
68    pub size: Option<u64>,
69
70    /// Used to request only a part of this file.
71    #[xml(child(default))]
72    pub range: Option<Range>,
73
74    /// A list of hashes matching this entire file.
75    #[xml(child(n = ..))]
76    pub hashes: Vec<Hash>,
77}
78
79impl File {
80    /// Creates a new file descriptor.
81    pub fn new() -> File {
82        File::default()
83    }
84
85    /// Sets the date of last modification on this file.
86    pub fn with_date(mut self, date: DateTime) -> File {
87        self.date = Some(date);
88        self
89    }
90
91    /// Sets the date of last modification on this file from an ISO-8601
92    /// string.
93    pub fn with_date_str(mut self, date: &str) -> Result<File, Error> {
94        self.date = Some(DateTime::from_str(date).map_err(Error::text_parse_error)?);
95        Ok(self)
96    }
97
98    /// Sets the MIME type of this file.
99    pub fn with_media_type(mut self, media_type: String) -> File {
100        self.media_type = Some(media_type);
101        self
102    }
103
104    /// Sets the name of this file.
105    pub fn with_name(mut self, name: String) -> File {
106        self.name = Some(name);
107        self
108    }
109
110    /// Sets a description for this file.
111    pub fn add_desc(mut self, lang: &str, desc: String) -> File {
112        self.descs.insert(Lang::from(lang), desc);
113        self
114    }
115
116    /// Sets the file size of this file, in bytes.
117    pub fn with_size(mut self, size: u64) -> File {
118        self.size = Some(size);
119        self
120    }
121
122    /// Request only a range of this file.
123    pub fn with_range(mut self, range: Range) -> File {
124        self.range = Some(range);
125        self
126    }
127
128    /// Add a hash on this file.
129    pub fn add_hash(mut self, hash: Hash) -> File {
130        self.hashes.push(hash);
131        self
132    }
133}
134
135/// A wrapper element for a file.
136#[derive(FromXml, AsXml, Debug, Clone, Default)]
137#[xml(namespace = ns::JINGLE_FT, name = "description")]
138pub struct Description {
139    /// The actual file descriptor.
140    #[xml(child)]
141    pub file: File,
142}
143
144/// A checksum for checking that the file has been transferred correctly.
145#[derive(FromXml, AsXml, Debug, Clone)]
146#[xml(namespace = ns::JINGLE_FT, name = "checksum")]
147pub struct Checksum {
148    /// The identifier of the file transfer content.
149    #[xml(attribute)]
150    pub name: ContentId,
151
152    /// The creator of this file transfer.
153    #[xml(attribute)]
154    pub creator: Creator,
155
156    /// The file being checksummed.
157    #[xml(child)]
158    pub file: File,
159}
160
161/// A notice that the file transfer has been completed.
162#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
163#[xml(namespace = ns::JINGLE_FT, name = "received")]
164pub struct Received {
165    /// The content identifier of this Jingle session.
166    #[xml(attribute)]
167    pub name: ContentId,
168
169    /// The creator of this file transfer.
170    #[xml(attribute)]
171    pub creator: Creator,
172}
173
174#[cfg(test)]
175mod tests {
176    use super::*;
177    use crate::hashes::Algo;
178    use base64::{engine::general_purpose::STANDARD as Base64, Engine};
179    use minidom::Element;
180    use xso::error::FromElementError;
181
182    // Apparently, i686 and AArch32/PowerPC seem to disagree here. So instead
183    // of trying to figure this out now, we just ignore the test.
184    #[cfg(target_pointer_width = "32")]
185    #[test]
186    #[ignore]
187    fn test_size() {
188        assert_size!(Range, 32);
189        assert_size!(File, 104);
190        assert_size!(Description, 104);
191        assert_size!(Checksum, 128);
192        assert_size!(Received, 16);
193    }
194
195    #[cfg(target_pointer_width = "64")]
196    #[test]
197    fn test_size() {
198        assert_size!(Range, 48);
199        assert_size!(File, 176);
200        assert_size!(Description, 176);
201        assert_size!(Checksum, 208);
202        assert_size!(Received, 32);
203    }
204
205    #[test]
206    fn test_description() {
207        let elem: Element = r#"<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
208  <file>
209    <media-type>text/plain</media-type>
210    <name>test.txt</name>
211    <date>2015-07-26T21:46:00+01:00</date>
212    <size>6144</size>
213    <hash xmlns='urn:xmpp:hashes:2'
214          algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
215  </file>
216</description>
217"#
218        .parse()
219        .unwrap();
220        let desc = Description::try_from(elem).unwrap();
221        assert_eq!(desc.file.media_type, Some(String::from("text/plain")));
222        assert_eq!(desc.file.name, Some(String::from("test.txt")));
223        assert_eq!(desc.file.descs, BTreeMap::new());
224        assert_eq!(
225            desc.file.date,
226            DateTime::from_str("2015-07-26T21:46:00+01:00").ok()
227        );
228        assert_eq!(desc.file.size, Some(6144u64));
229        assert_eq!(desc.file.range, None);
230        assert_eq!(desc.file.hashes[0].algo, Algo::Sha_1);
231        assert_eq!(
232            desc.file.hashes[0].hash,
233            Base64.decode("w0mcJylzCn+AfvuGdqkty2+KP48=").unwrap()
234        );
235    }
236
237    #[test]
238    fn test_request() {
239        let elem: Element = r#"<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
240  <file>
241    <hash xmlns='urn:xmpp:hashes:2'
242          algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
243  </file>
244</description>
245"#
246        .parse()
247        .unwrap();
248        let desc = Description::try_from(elem).unwrap();
249        assert_eq!(desc.file.media_type, None);
250        assert_eq!(desc.file.name, None);
251        assert_eq!(desc.file.descs, BTreeMap::new());
252        assert_eq!(desc.file.date, None);
253        assert_eq!(desc.file.size, None);
254        assert_eq!(desc.file.range, None);
255        assert_eq!(desc.file.hashes[0].algo, Algo::Sha_1);
256        assert_eq!(
257            desc.file.hashes[0].hash,
258            Base64.decode("w0mcJylzCn+AfvuGdqkty2+KP48=").unwrap()
259        );
260    }
261
262    #[test]
263    // TODO: Reenable that test once we correctly treat same @xml:lang as errors!
264    #[ignore]
265    fn test_descs() {
266        let elem: Element = r#"<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
267  <file>
268    <media-type>text/plain</media-type>
269    <desc xml:lang='fr'>Fichier secret !</desc>
270    <desc xml:lang='en'>Secret file!</desc>
271    <hash xmlns='urn:xmpp:hashes:2'
272          algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
273  </file>
274</description>
275"#
276        .parse()
277        .unwrap();
278        let desc = Description::try_from(elem).unwrap();
279        assert_eq!(
280            desc.file.descs.keys().cloned().collect::<Vec<_>>(),
281            ["en", "fr"]
282        );
283        assert_eq!(desc.file.descs["en"], String::from("Secret file!"));
284        assert_eq!(desc.file.descs["fr"], String::from("Fichier secret !"));
285
286        let elem: Element = r#"<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
287  <file>
288    <media-type>text/plain</media-type>
289    <desc xml:lang='fr'>Fichier secret !</desc>
290    <desc xml:lang='fr'>Secret file!</desc>
291    <hash xmlns='urn:xmpp:hashes:2'
292          algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
293  </file>
294</description>
295"#
296        .parse()
297        .unwrap();
298        let error = Description::try_from(elem).unwrap_err();
299        let message = match error {
300            FromElementError::Invalid(Error::Other(string)) => string,
301            _ => panic!(),
302        };
303        assert_eq!(message, "Desc element present twice for the same xml:lang.");
304    }
305
306    #[test]
307    fn test_received_valid() {
308        let elem: Element = "<received xmlns='urn:xmpp:jingle:apps:file-transfer:5' name='coucou' creator='initiator'/>".parse().unwrap();
309        let received = Received::try_from(elem).unwrap();
310        assert_eq!(received.name, ContentId(String::from("coucou")));
311        assert_eq!(received.creator, Creator::Initiator);
312        let elem2 = Element::from(received.clone());
313        let received2 = Received::try_from(elem2).unwrap();
314        assert_eq!(received2.name, ContentId(String::from("coucou")));
315        assert_eq!(received2.creator, Creator::Initiator);
316    }
317
318    #[test]
319    #[cfg_attr(feature = "disable-validation", should_panic = "Result::unwrap_err")]
320    fn test_received_unknown_child() {
321        let elem: Element = "<received xmlns='urn:xmpp:jingle:apps:file-transfer:5' name='coucou' creator='initiator'><coucou/></received>".parse().unwrap();
322        let error = Received::try_from(elem).unwrap_err();
323        let message = match error {
324            FromElementError::Invalid(Error::Other(string)) => string,
325            _ => panic!(),
326        };
327        assert_eq!(message, "Unknown child in Received element.");
328    }
329
330    #[test]
331    fn test_received_missing_name() {
332        let elem: Element =
333            "<received xmlns='urn:xmpp:jingle:apps:file-transfer:5' creator='initiator'/>"
334                .parse()
335                .unwrap();
336        let error = Received::try_from(elem).unwrap_err();
337        let message = match error {
338            FromElementError::Invalid(Error::Other(string)) => string,
339            _ => panic!(),
340        };
341        assert_eq!(
342            message,
343            "Required attribute field 'name' on Received element missing."
344        );
345    }
346
347    #[test]
348    fn test_received_invalid_creator() {
349        let elem: Element = "<received xmlns='urn:xmpp:jingle:apps:file-transfer:5' name='coucou' creator='coucou'/>".parse().unwrap();
350        let error = Received::try_from(elem).unwrap_err();
351        let message = match error {
352            FromElementError::Invalid(Error::TextParseError(string)) => string,
353            _ => panic!(),
354        };
355        assert_eq!(
356            message.to_string(),
357            "Unknown value for 'creator' attribute."
358        );
359    }
360
361    #[cfg(not(feature = "disable-validation"))]
362    #[test]
363    fn test_invalid_received() {
364        let elem: Element = "<received xmlns='urn:xmpp:jingle:apps:file-transfer:5' name='coucou' creator='initiator' coucou=''/>".parse().unwrap();
365        let error = Received::try_from(elem).unwrap_err();
366        let message = match error {
367            FromElementError::Invalid(Error::Other(string)) => string,
368            _ => panic!(),
369        };
370        assert_eq!(message, "Unknown attribute in Received element.");
371    }
372
373    #[test]
374    fn test_checksum_valid() {
375        let elem: Element = "<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5' name='coucou' creator='initiator'><file><hash xmlns='urn:xmpp:hashes:2' algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash></file></checksum>".parse().unwrap();
376        let hash = vec![
377            195, 73, 156, 39, 41, 115, 10, 127, 128, 126, 251, 134, 118, 169, 45, 203, 111, 138,
378            63, 143,
379        ];
380        let checksum = Checksum::try_from(elem).unwrap();
381        assert_eq!(checksum.name, ContentId(String::from("coucou")));
382        assert_eq!(checksum.creator, Creator::Initiator);
383        assert_eq!(
384            checksum.file.hashes,
385            vec!(Hash {
386                algo: Algo::Sha_1,
387                hash: hash.clone()
388            })
389        );
390        let elem2 = Element::from(checksum);
391        let checksum2 = Checksum::try_from(elem2).unwrap();
392        assert_eq!(checksum2.name, ContentId(String::from("coucou")));
393        assert_eq!(checksum2.creator, Creator::Initiator);
394        assert_eq!(
395            checksum2.file.hashes,
396            vec!(Hash {
397                algo: Algo::Sha_1,
398                hash: hash.clone()
399            })
400        );
401    }
402
403    #[test]
404    #[cfg_attr(feature = "disable-validation", should_panic = "Result::unwrap_err")]
405    fn test_checksum_unknown_child() {
406        let elem: Element = "<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5' name='coucou' creator='initiator'><file><hash xmlns='urn:xmpp:hashes:2' algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash></file><coucou/></checksum>".parse().unwrap();
407        let error = Checksum::try_from(elem).unwrap_err();
408        let message = match error {
409            FromElementError::Invalid(Error::Other(string)) => string,
410            other => panic!("unexpected error: {:?}", other),
411        };
412        assert_eq!(message, "Unknown child in Checksum element.");
413    }
414
415    #[test]
416    fn test_checksum_missing_name() {
417        let elem: Element = "<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5' creator='initiator'><file><hash xmlns='urn:xmpp:hashes:2' algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash></file></checksum>".parse().unwrap();
418        let error = Checksum::try_from(elem).unwrap_err();
419        let message = match error {
420            FromElementError::Invalid(Error::Other(string)) => string,
421            _ => panic!(),
422        };
423        assert_eq!(
424            message,
425            "Required attribute field 'name' on Checksum element missing."
426        );
427    }
428
429    #[test]
430    fn test_checksum_invalid_creator() {
431        let elem: Element = "<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5' name='coucou' creator='coucou'><file><hash xmlns='urn:xmpp:hashes:2' algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash></file></checksum>".parse().unwrap();
432        let error = Checksum::try_from(elem).unwrap_err();
433        let message = match error {
434            FromElementError::Invalid(Error::TextParseError(string)) => string,
435            _ => panic!(),
436        };
437        assert_eq!(
438            message.to_string(),
439            "Unknown value for 'creator' attribute."
440        );
441    }
442
443    #[cfg(not(feature = "disable-validation"))]
444    #[test]
445    fn test_invalid_checksum() {
446        let elem: Element = "<checksum xmlns='urn:xmpp:jingle:apps:file-transfer:5' name='coucou' creator='initiator' coucou=''><file><hash xmlns='urn:xmpp:hashes:2' algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash></file></checksum>".parse().unwrap();
447        let error = Checksum::try_from(elem).unwrap_err();
448        let message = match error {
449            FromElementError::Invalid(Error::Other(string)) => string,
450            _ => panic!(),
451        };
452        assert_eq!(message, "Unknown attribute in Checksum element.");
453    }
454
455    #[test]
456    fn test_range() {
457        let elem: Element = "<range xmlns='urn:xmpp:jingle:apps:file-transfer:5'/>"
458            .parse()
459            .unwrap();
460        let range = Range::try_from(elem).unwrap();
461        assert_eq!(range.offset, 0);
462        assert_eq!(range.length, None);
463        assert_eq!(range.hashes, vec!());
464
465        let elem: Element = "<range xmlns='urn:xmpp:jingle:apps:file-transfer:5' offset='2048' length='1024'><hash xmlns='urn:xmpp:hashes:2' algo='sha-1'>kHp5RSzW/h7Gm1etSf90Mr5PC/k=</hash></range>".parse().unwrap();
466        let hashes = vec![Hash {
467            algo: Algo::Sha_1,
468            hash: vec![
469                144, 122, 121, 69, 44, 214, 254, 30, 198, 155, 87, 173, 73, 255, 116, 50, 190, 79,
470                11, 249,
471            ],
472        }];
473        let range = Range::try_from(elem).unwrap();
474        assert_eq!(range.offset, 2048);
475        assert_eq!(range.length, Some(1024));
476        assert_eq!(range.hashes, hashes);
477        let elem2 = Element::from(range);
478        let range2 = Range::try_from(elem2).unwrap();
479        assert_eq!(range2.offset, 2048);
480        assert_eq!(range2.length, Some(1024));
481        assert_eq!(range2.hashes, hashes);
482    }
483
484    #[cfg(not(feature = "disable-validation"))]
485    #[test]
486    fn test_invalid_range() {
487        let elem: Element = "<range xmlns='urn:xmpp:jingle:apps:file-transfer:5' coucou=''/>"
488            .parse()
489            .unwrap();
490        let error = Range::try_from(elem).unwrap_err();
491        let message = match error {
492            FromElementError::Invalid(Error::Other(string)) => string,
493            _ => panic!(),
494        };
495        assert_eq!(message, "Unknown attribute in Range element.");
496    }
497}
xmpp_parsers/jingle_ft.rs

xmpp_parsers/
jingle_ft.rs
