vcon 0.3.0

A library for vCons. It reads and checks a vCon: form, compression, uuid and critical extensions.
Documentation 
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
102
103
104
105
106
107

// The crate's page on docs.rs is its README, so the example there runs as
// a doc test.
#![doc = include_str!("../README.md")]

use std::fmt;

use uuid::Uuid;

mod critical;
mod form;
mod gzip;
mod identity;
#[cfg(test)]
mod ietf_examples;
mod json;
pub mod read;
mod signed;
pub mod write;

/// Reads a uuid written in RFC 9562 text form, 8-4-4-4-12 hex digits in
/// either case, as a vCon's uuid must be; no other spelling is taken.
///
/// ```
/// let text = "01A07DA8-C2BB-83E5-B9A2-279E0D16BC46";
/// let uuid = vcon::parse_uuid(text).expect("8-4-4-4-12 hex digits");
/// assert_eq!(
///     uuid.to_string(),
///     "01a07da8-c2bb-83e5-b9a2-279e0d16bc46",
///     "upper case hex reads as the same uuid"
/// );
/// let bare = "01a07da8c2bb83e5b9a2279e0d16bc46";
/// assert_eq!(vcon::parse_uuid(bare), None, "without hyphens it is not RFC 9562 text form");
/// ```
#[must_use]
pub fn parse_uuid(text: &str) -> Option<Uuid> {
    identity::parse_uuid_text(text).ok()
}

/// The three forms a vCon can take. A later release may add one, so a
/// `match` on it outside this crate needs a wildcard arm.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Form {
    /// Plain JSON.
    Unsigned,
    /// A JWS whose payload is the vCon.
    Signed,
    /// A JWE whose ciphertext is a signed vCon.
    Encrypted,
}

impl Form {
    /// The form's name in lower case: `unsigned`, `signed` or `encrypted`.
    ///
    /// ```
    /// assert_eq!(vcon::Form::Signed.as_str(), "signed", "a JWS is the signed form");
    /// ```
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Form::Unsigned => "unsigned",
            Form::Signed => "signed",
            Form::Encrypted => "encrypted",
        }
    }
}

/// Writes [`Form::as_str`].
impl fmt::Display for Form {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

/// The crate's name is not part of its API:
///
/// ```compile_fail,E0425
/// let _ = vcon::CRATE_NAME;
/// ```
#[cfg(doctest)]
pub struct NoCrateName;

#[cfg(test)]
mod tests {
    use super::Form;

    #[test]
    fn each_form_has_its_lower_case_name() {
        let names = [
            (Form::Unsigned, "unsigned"),
            (Form::Signed, "signed"),
            (Form::Encrypted, "encrypted"),
        ];
        for (form, name) in names {
            assert_eq!(
                form.as_str(),
                name,
                "as_str gives the form's name in lower case: {form:?}"
            );
            assert_eq!(
                form.to_string(),
                name,
                "Display writes what as_str gives: {form:?}"
            );
        }
    }
}