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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
use bc_components::{tags, ARID};
use dcbor::prelude::*;

use crate::{EnvelopeEncodable, Envelope, EnvelopeError};
use crate::extension::known_values;

use super::{Function, Parameter};

/// Envelope Expressions: Function Construction
impl Envelope {
    /// Creates an envelope with a `«function»` subject.
    pub fn new_function(function: impl Into<Function>) -> Self {
        Envelope::new(function.into())
    }
}

/// Envelope Expressions: Parameter Construction
impl Envelope {
    /// Creates a new envelope containing a `❰parameter❱: value` assertion.
    ///
    /// - Parameters:
    ///   - param: A ``Parameter``. This will be encoded as either an unsigned integer or a string.
    ///   - value: The argument value.
    ///
    /// - Returns: The new assertion envelope. If `value` is `None`, returns `None`.
    pub fn new_parameter(param: impl Into<Parameter>, value: impl EnvelopeEncodable) -> Self {
        Self::new_assertion(param.into(), value)
    }

    /// Optionally adds a `❰parameter❱: value` assertion to the envelope.
    pub fn new_optional_parameter(param: impl Into<Parameter>, value: Option<impl EnvelopeEncodable>) -> Option<Self> {
        value.map(|value| Self::new_parameter(param, value))
    }

    /// Adds a `❰parameter❱: value` assertion to the envelope.
    ///
    /// - Parameters:
    ///   - param: A ``Parameter``. This will be encoded as either an unsigned integer or a string.
    ///   - value: The argument value.
    ///
    /// - Returns: The new envelope.
    pub fn add_parameter(&self, param: impl Into<Parameter>, value: impl EnvelopeEncodable) -> Self {
        self.add_assertion_envelope(Self::new_parameter(param, value))
            .unwrap()
    }

    /// Optionally adds a `❰parameter❱: value` assertion to the envelope.
    ///
    /// - Parameters:
    ///   - param: A ``Parameter``. This will be encoded as either an unsigned integer or a string.
    ///   - value: The optional argument value.
    ///
    /// - Returns: The new envelope. If `value` is `None`, returns the original envelope.
    pub fn add_optional_parameter(
        &self,
        param: impl Into<Parameter>,
        value: Option<impl EnvelopeEncodable>,
    ) -> Self {
        self.add_optional_assertion_envelope(Self::new_optional_parameter(param, value))
            .unwrap()
    }
}

/// Envelope Expressions: Request Construction
impl Envelope {
    /// Creates an envelope with an `ARID` subject and a `body: «function»`
    /// assertion.
    ///
    /// Also adds a `'note'` assertion if `note` is not empty, and a
    /// `'date'` assertion if `date` is not `nil`.
    pub fn new_request_with_metadata(id: impl AsRef<ARID>, body: impl EnvelopeEncodable, note: impl Into<String>, date: Option<dcbor::Date>) -> Self {
        let note = note.into();
        Envelope::new(CBOR::tagged_value(tags::REQUEST, id.as_ref()))
            .add_assertion(known_values::BODY, body)
            .add_assertion_if(!note.is_empty(), known_values::NOTE, note)
            .add_optional_assertion(known_values::DATE, date)
    }

    /// Creates an envelope with an `ARID` subject and a `body: «function»` assertion.
    pub fn new_request(id: impl AsRef<ARID>, body: impl EnvelopeEncodable) -> Self {
        Envelope::new_request_with_metadata(id, body, "", None)
    }
}

/// Envelope Expression: Request Parsing
impl Envelope {
    pub fn request_id(&self) -> anyhow::Result<ARID> {
        let id = self
            .subject()
            .expect_leaf()?
            .expect_tagged_value(tags::REQUEST)?
            .try_into()?;
        Ok(id)
    }

    pub fn request_body(&self) -> Result<Self, EnvelopeError> {
        self.object_for_predicate(known_values::BODY)
    }

    pub fn request_note(&self) -> anyhow::Result<String> {
        self.extract_object_for_predicate(known_values::NOTE)
    }

    pub fn request_date(&self) -> anyhow::Result<Option<dcbor::Date>> {
        self.extract_optional_object_for_predicate(known_values::DATE)
    }
}

/// Envelope Expressions: Response Construction
impl Envelope {
    /// Creates an envelope with an `ARID` subject and a `result: value` assertion.
    pub fn new_response(response_id: impl AsRef<ARID>, result: impl EnvelopeEncodable) -> Self {
        Envelope::new(CBOR::tagged_value(tags::RESPONSE, response_id.as_ref()))
            .add_assertion(known_values::RESULT, result)
    }

    /// Creates an envelope with an `ARID` subject and a `result: value` assertion for each provided result.
    pub fn new_response_with_result(response_id: impl AsRef<ARID>, results: &[impl EnvelopeEncodable + Clone]) -> Self {
        let mut envelope = Envelope::new(CBOR::tagged_value(tags::RESPONSE, response_id.as_ref()));

        for result in results {
            envelope = envelope.add_assertion(
                known_values::RESULT,
                result,
            );
        }

        envelope
    }

    /// Creates an error response envelope.
    ///
    /// If `response_id` is `None`, the subject will be `unknown`.
    /// Used for an immediate response to a request without a proper ID, for example
    /// when a encrypted request envelope is received and the decryption fails, making
    /// it impossible to extract the request ID.
    ///
    /// If `error` is `None`, no assertion will be added.
    ///
    pub fn new_error_response(response_id: Option<&ARID>, error: Option<impl EnvelopeEncodable>) -> Self {
        let response_id = match response_id {
            Some(id) => id.cbor(),
            None => known_values::UNKNOWN_VALUE.cbor(),
        };
        if let Some(error) = error {
            Envelope::new(CBOR::tagged_value(tags::RESPONSE, response_id))
                .add_assertion(known_values::ERROR, error)
        } else {
            Envelope::new(CBOR::tagged_value(tags::RESPONSE, response_id))
        }
    }
}

/// Envelope Expressions: Parameter Decoding
impl Envelope {
    pub fn object_for_parameter(&self, param: impl Into<Parameter>) -> anyhow::Result<Envelope> {
        Ok(self.object_for_predicate(param.into())?)
    }

    pub fn objects_for_parameter(&self, param: impl Into<Parameter>) -> Vec<Envelope> {
        self.objects_for_predicate(param.into())
    }

    /// Returns the argument for the given parameter, decoded as the given type.
    ///
    /// - Throws: Throws an exception if there is not exactly one matching `parameter`,
    /// or if the parameter value is not the correct type.
    pub fn extract_object_for_parameter<T>(&self, param: impl Into<Parameter>) -> anyhow::Result<T>
    where
        T: CBORDecodable + 'static,
    {
        self.extract_object_for_predicate(param.into())
    }

    /// Returns the argument for the given parameter, or `None` if there is no matching parameter.
    pub fn extract_optional_object_for_parameter<T: CBORDecodable + 'static>(&self, param: impl Into<Parameter>) -> anyhow::Result<Option<T>> {
        self.extract_optional_object_for_predicate(param.into())
    }

    /// Returns an array of arguments for the given parameter, decoded as the given type.
    ///
    /// - Throws: Throws an exception if any of the parameter values are not the correct type.
    pub fn extract_objects_for_parameter<T>(&self, param: impl Into<Parameter>) -> anyhow::Result<Vec<T>>
    where
        T: CBORDecodable + 'static,
    {
        self.extract_objects_for_predicate(param.into())
    }
}

/// Envelope Expressions: Result Decoding
impl Envelope {
    pub fn response_id(&self) -> anyhow::Result<ARID> {
        let id = self
            .subject()
            .expect_leaf()?
            .expect_tagged_value(tags::RESPONSE)?
            .try_into()?;
        Ok(id)
    }

    /// Returns the object of the `result` predicate.
    ///
    /// - Throws: Throws an exception if there is no `result` predicate.
    pub fn result(&self) -> Result<Self, EnvelopeError> {
        self.object_for_predicate(known_values::RESULT)
    }

    /// Returns the objects of every `result` predicate.
    pub fn results(&self) -> Vec<Self> {
        self.objects_for_predicate(known_values::RESULT)
    }

    /// Returns the object of the `result` predicate, decoded as the given type.
    ///
    /// - Throws: Throws an exception if there is no `result` predicate, or if its
    /// object cannot be decoded to the specified `type`.
    pub fn extract_result<T>(&self) -> anyhow::Result<T>
    where
        T: CBORDecodable + 'static,
    {
        self.extract_object_for_predicate(known_values::RESULT)
    }

    /// Returns the objects of every `result` predicate, decoded as the given type.
    ///
    /// - Throws: Throws an if not all object cannot be decoded to the specified `type`.
    pub fn extract_results<T>(&self) -> anyhow::Result<Vec<T>>
    where
        T: CBORDecodable + 'static,
    {
        self.extract_objects_for_predicate(known_values::RESULT)
    }

    /// Returns whether the `result` predicate has the `KnownValue` `.ok`.
    ///
    /// - Throws: Throws an exception if there is no `result` predicate.
    pub fn is_result_ok(&self) -> anyhow::Result<bool> {
        if let Some(k) = self.result()?.known_value() {
            return Ok(k == &known_values::OK_VALUE);
        }
        Ok(false)
    }

    /// Returns the error value, decoded as the given type.
    ///
    /// - Throws: Throws an exception if there is no `error` predicate.
    pub fn error<T>(&self) -> anyhow::Result<T>
    where
        T: CBORDecodable + 'static,
    {
        self.extract_object_for_predicate(known_values::ERROR)
    }

    /// Returns whether the envelope is an error response.
    pub fn is_error(&self) -> bool {
        self.assertion_with_predicate(known_values::ERROR).is_ok()
    }
}