nitr-std 0.0.0-beta.7

The built-in `nitr.*` standard library for Nitr: dbg, fetch, template, json, http, log, crypto, and the SQLite driver.
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
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
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
// SPDX-License-Identifier: MIT OR Apache-2.0
// This file is part of Nitr.
// See https://nitrweb.com/ for more information
// Copyright (C) 2024-present Jose Quintana <joseluisq.net>

//! Test doubles for `nitr test`: canned outbound responses and
//! environment overrides, installed by a test as **data** and read by the
//! standard library at the seams that honour them.
//!
//! A test file and the server's pooled states are separate Lua universes,
//! so a double cannot be a Lua function patched into `nitr.*`: it would
//! change the test's state and nothing a handler sees. Instead the runner
//! puts one [`Doubles`] into the app data of every state it builds — the
//! pooled ones through `ServerBuilder::setup`, which also runs on a
//! poison rebuild and a reload, and its own test state directly — and the
//! setters live under `nitr.test`, which only the runner registers.
//!
//! Absent app data means no double: that is the production path, and it
//! costs each seam one app-data lookup. The types here are plain data, so
//! the module compiles in every feature set even though the fetch seam
//! exists only with `fetch`.

use std::collections::{HashMap, VecDeque};
use std::sync::{Arc, Mutex, MutexGuard, RwLock};

use mlua::Lua;

/// How many outbound calls a test records before the oldest are dropped:
/// a chatty handler must not grow the record without bound.
pub const MAX_RECORDED_CALLS: usize = 10_000;

/// Every double a test can install, shared by the test state and every
/// pooled state of the server under test.
#[derive(Debug, Default)]
pub struct Doubles {
    fetch: Mutex<FetchMock>,
    /// Environment overrides: `Some(value)` sets, `None` unsets.
    env: RwLock<HashMap<String, Option<String>>>,
}

impl Doubles {
    /// An empty set of doubles, ready to share.
    pub fn new() -> Arc<Self> {
        Arc::new(Self::default())
    }

    /// Clears every double: rules, recorded calls, the strict flag and
    /// the environment overrides. The runner calls it before every test.
    pub fn reset(&self) {
        if let Ok(mut fetch) = self.fetch.lock() {
            *fetch = FetchMock::default();
        }
        if let Ok(mut env) = self.env.write() {
            env.clear();
        }
    }

    /// The outbound-request double.
    ///
    /// # Errors
    ///
    /// Only when a panic poisoned the lock, which nothing here can cause.
    pub fn fetch(&self) -> mlua::Result<MutexGuard<'_, FetchMock>> {
        self.fetch
            .lock()
            .map_err(|_| mlua::Error::RuntimeError("the fetch double lock is poisoned".into()))
    }

    /// Overrides one environment variable: `Some` sets it, `None` makes it
    /// read as unset. The `[env]` policy still applies on top.
    pub fn set_env(&self, name: &str, value: Option<String>) {
        if let Ok(mut env) = self.env.write() {
            env.insert(name.to_string(), value);
        }
    }

    /// Removes every environment override.
    pub fn reset_env(&self) {
        if let Ok(mut env) = self.env.write() {
            env.clear();
        }
    }

    /// The override for `name`, when one is installed: `Some(None)` is an
    /// explicit unset.
    pub(crate) fn env_override(&self, name: &str) -> Option<Option<String>> {
        self.env.read().ok()?.get(name).cloned()
    }
}

/// The doubles installed on this state, if any.
pub(crate) fn installed(lua: &Lua) -> Option<Arc<Doubles>> {
    lua.app_data_ref::<Arc<Doubles>>().map(|d| d.clone())
}

/// How a rule matches a request URL.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum UrlMatch {
    /// The whole URL, as the client serializes it.
    Exact(String),
    /// A prefix, written with a trailing `*` (`https://api.example/*`).
    Prefix(String),
}

impl UrlMatch {
    fn matches(&self, url: &str) -> bool {
        match self {
            UrlMatch::Exact(expected) => url == expected,
            UrlMatch::Prefix(prefix) => url.starts_with(prefix.as_str()),
        }
    }
}

/// One canned answer for `nitr.fetch`.
#[derive(Debug, Clone)]
pub struct FetchRule {
    /// The method to match, uppercase; `None` matches any.
    pub method: Option<String>,
    /// The URL to match.
    pub url: UrlMatch,
    /// The status of the canned response.
    pub status: u16,
    /// Its headers, in order.
    pub headers: Vec<(String, String)>,
    /// Its body.
    pub body: Vec<u8>,
    /// How many requests it answers before falling through; `None` is
    /// unlimited.
    pub times: Option<u32>,
    /// A transport failure to raise instead of answering: the request
    /// fails the way a reset or a timeout would, and is retryable.
    pub error: Option<String>,
}

/// The failure a `t.fetch.mock { error = ... }` rule raises.
#[derive(Debug)]
pub struct MockedFailure(pub String);

impl std::fmt::Display for MockedFailure {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "fetch failed (mocked): {}", self.0)
    }
}

impl std::error::Error for MockedFailure {}

/// One outbound call made while the doubles were installed, whether a
/// rule answered it or not.
#[derive(Debug, Clone)]
pub struct FetchCall {
    /// The request method, uppercase.
    pub method: String,
    /// The URL as the client serialized it.
    pub url: String,
    /// The request headers, in order.
    pub headers: Vec<(String, String)>,
    /// The request body, when it had one.
    pub body: Option<Vec<u8>>,
    /// Whether a rule answered it.
    pub mocked: bool,
}

/// The canned response a matched rule produced.
#[derive(Debug, Clone)]
pub struct Canned {
    /// Response status.
    pub status: u16,
    /// Response headers, in order.
    pub headers: Vec<(String, String)>,
    /// Response body.
    pub body: Vec<u8>,
}

/// What the double says about one outbound request.
#[derive(Debug)]
pub enum FetchAnswer {
    /// A rule matched: answer with this instead of sending.
    Canned(Canned),
    /// A rule matched and stands for a transport failure.
    Error(String),
    /// No rule matched and the double is not strict: send it for real,
    /// down the unchanged path, policy and resolver included.
    PassThrough,
    /// No rule matched and the double is strict: refuse.
    Refused,
}

/// Canned responses, the recorded calls, and the strict flag.
#[derive(Debug, Default)]
pub struct FetchMock {
    rules: Vec<FetchRule>,
    calls: VecDeque<FetchCall>,
    strict: bool,
    dropped: u64,
}

impl FetchMock {
    /// Adds a rule; rules are tried in the order they were added.
    pub fn add(&mut self, rule: FetchRule) {
        self.rules.push(rule);
    }

    /// Whether an unmatched request is refused instead of sent.
    pub fn set_strict(&mut self, strict: bool) {
        self.strict = strict;
    }

    /// The calls recorded so far, oldest first.
    pub fn calls(&self) -> impl Iterator<Item = &FetchCall> {
        self.calls.iter()
    }

    /// How many of the oldest calls were dropped past
    /// [`MAX_RECORDED_CALLS`].
    pub fn dropped(&self) -> u64 {
        self.dropped
    }

    /// Records one outbound request and decides its fate: the first rule
    /// that matches (method and URL) and has uses left answers it and
    /// spends one use.
    pub fn answer(
        &mut self,
        method: &str,
        url: &str,
        headers: Vec<(String, String)>,
        body: Option<Vec<u8>>,
    ) -> FetchAnswer {
        let rule = self.rules.iter_mut().find(|rule| {
            rule.method
                .as_deref()
                .is_none_or(|m| m.eq_ignore_ascii_case(method))
                && rule.url.matches(url)
                && rule.times.is_none_or(|left| left > 0)
        });
        let answer = match rule {
            Some(rule) => {
                if let Some(left) = &mut rule.times {
                    *left -= 1;
                }
                match &rule.error {
                    Some(message) => FetchAnswer::Error(message.clone()),
                    None => FetchAnswer::Canned(Canned {
                        status: rule.status,
                        headers: rule.headers.clone(),
                        body: rule.body.clone(),
                    }),
                }
            }
            None if self.strict => FetchAnswer::Refused,
            None => FetchAnswer::PassThrough,
        };
        if self.calls.len() >= MAX_RECORDED_CALLS {
            self.calls.pop_front();
            self.dropped += 1;
        }
        self.calls.push_back(FetchCall {
            method: method.to_ascii_uppercase(),
            url: url.to_string(),
            headers,
            body,
            mocked: matches!(answer, FetchAnswer::Canned(_) | FetchAnswer::Error(_)),
        });
        answer
    }
}

/// The value `session:save` would write for `data`: the JSON payload
/// (with the expiry when `max_age` is set) signed for `name` — so a test
/// can put a session into a client's jar without a login round trip.
///
/// # Errors
///
/// The same as `session:save`: a secret under 16 bytes, reserved keys,
/// values that are not JSON, or a payload over the cookie bound.
pub fn session_cookie_value(
    data: &mlua::Table,
    name: &str,
    secret: &str,
    max_age: Option<i64>,
) -> mlua::Result<String> {
    crate::session::signed_value(data, name, secret, max_age)
}

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

    fn rule(method: Option<&str>, url: UrlMatch, times: Option<u32>) -> FetchRule {
        FetchRule {
            method: method.map(str::to_string),
            url,
            status: 202,
            headers: vec![("content-type".into(), "text/plain".into())],
            body: b"canned".to_vec(),
            times,
            error: None,
        }
    }

    fn status(answer: FetchAnswer) -> Option<u16> {
        match answer {
            FetchAnswer::Canned(c) => Some(c.status),
            _ => None,
        }
    }

    #[test]
    fn exact_and_prefix_rules_match_what_they_say() {
        let mut mock = FetchMock::default();
        mock.add(rule(
            None,
            UrlMatch::Exact("https://hooks.example/notes".into()),
            None,
        ));
        mock.add(rule(
            None,
            UrlMatch::Prefix("https://api.example/".into()),
            None,
        ));
        let mut ask = |url: &str| status(mock.answer("GET", url, Vec::new(), None));
        assert_eq!(ask("https://hooks.example/notes"), Some(202));
        assert_eq!(ask("https://hooks.example/notes/1"), None, "exact is exact");
        assert_eq!(ask("https://api.example/v1/rates"), Some(202));
        assert_eq!(
            ask("https://api.example.evil/"),
            None,
            "a prefix is a string prefix"
        );
    }

    #[test]
    fn methods_and_times_narrow_a_rule_and_the_first_match_wins() {
        let mut mock = FetchMock::default();
        mock.add(rule(
            Some("POST"),
            UrlMatch::Prefix("https://x/".into()),
            Some(1),
        ));
        let mut fallback = rule(None, UrlMatch::Prefix("https://x/".into()), None);
        fallback.status = 503;
        mock.add(fallback);
        assert_eq!(
            status(mock.answer("get", "https://x/a", Vec::new(), None)),
            Some(503)
        );
        assert_eq!(
            status(mock.answer("post", "https://x/a", Vec::new(), None)),
            Some(202)
        );
        assert_eq!(
            status(mock.answer("POST", "https://x/a", Vec::new(), None)),
            Some(503),
            "a spent rule falls through to the next"
        );
    }

    #[test]
    fn strict_refuses_what_no_rule_matches_and_every_call_is_recorded() {
        let mut mock = FetchMock::default();
        mock.add(rule(None, UrlMatch::Exact("https://x/a".into()), None));
        assert!(matches!(
            mock.answer("GET", "https://x/b", Vec::new(), None),
            FetchAnswer::PassThrough
        ));
        mock.set_strict(true);
        assert!(matches!(
            mock.answer("GET", "https://x/b", Vec::new(), None),
            FetchAnswer::Refused
        ));
        mock.answer(
            "post",
            "https://x/a",
            vec![("x-signature".into(), "sha256=1".into())],
            Some(b"{}".to_vec()),
        );
        let calls: Vec<_> = mock.calls().collect();
        assert_eq!(calls.len(), 3);
        assert_eq!(calls[2].method, "POST");
        assert!(calls[2].mocked);
        assert!(!calls[1].mocked);
        assert_eq!(calls[2].body.as_deref(), Some(&b"{}"[..]));
    }

    #[test]
    fn the_call_record_is_bounded() {
        let mut mock = FetchMock::default();
        for i in 0..MAX_RECORDED_CALLS + 5 {
            mock.answer("GET", &format!("https://x/{i}"), Vec::new(), None);
        }
        assert_eq!(mock.calls().count(), MAX_RECORDED_CALLS);
        assert_eq!(mock.dropped(), 5);
        assert_eq!(
            mock.calls().next().map(|c| c.url.as_str()),
            Some("https://x/5"),
            "the oldest go first"
        );
    }

    #[test]
    fn reset_clears_every_double() {
        let doubles = Doubles::new();
        doubles.set_env("APP_KEY", Some("k".into()));
        doubles
            .fetch()
            .expect("fetch")
            .add(rule(None, UrlMatch::Prefix("https://".into()), None));
        doubles.fetch().expect("fetch").set_strict(true);
        doubles.reset();
        assert_eq!(doubles.env_override("APP_KEY"), None);
        let mut fetch = doubles.fetch().expect("fetch");
        assert!(matches!(
            fetch.answer("GET", "https://x/", Vec::new(), None),
            FetchAnswer::PassThrough
        ));
    }
}