Skip to main content

nitr_http/testing/
mod.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2// This file is part of Nitr.
3// See https://nitrweb.com/ for more information
4// Copyright (C) 2024-present Jose Quintana <joseluisq.net>
5
6//! In-process testing: dispatch requests through the full protection /
7//! router / middleware / handler path without binding a socket. This is
8//! the foundation of `nitr test` and of Rust-level integration tests.
9//!
10//! Also here, because they need crate-private types: the request options
11//! `nitr.test.request` understands ([`TestRequest`]), the fake request and
12//! the in-state application `nitr test` unit tests use ([`fake_request`],
13//! [`load_app`]), the server-sent-events parser behind `resp:sse()`
14//! ([`parse_sse`]), and the watcher behind `nitr test --watch`.
15
16use std::net::SocketAddr;
17use std::path::{Path, PathBuf};
18use std::sync::{Arc, RwLock};
19use std::time::Duration;
20
21use http_body_util::{BodyExt as _, Full};
22use hyper::body::Bytes;
23use hyper::{Method, Request, Uri};
24use tokio::sync::Semaphore;
25use tracing::Instrument as _;
26
27use crate::handler;
28use crate::protect::Protection;
29use crate::request::LuaRequest;
30use crate::server::current_pool;
31use nitr_core::{Error, ErrorInfo, Result, RuntimePool};
32
33mod request;
34mod sse;
35mod unit;
36
37pub use request::TestRequest;
38pub use sse::{SseEvent, parse_sse};
39pub use unit::{fake_request, load_app};
40
41/// The peer a request comes from when the test does not say.
42const DEFAULT_PEER: ([u8; 4], u16) = ([127, 0, 0, 1], 0);
43
44/// An in-process client for a built [`Server`](crate::Server); obtained
45/// via [`Server::test_client()`](crate::Server::test_client).
46#[derive(Clone)]
47pub struct TestClient {
48    pool: Arc<RwLock<Arc<RuntimePool>>>,
49    streams: Arc<Semaphore>,
50    protection: Arc<Protection>,
51    /// What `req.uri.scheme` reports: the server's `[tls]` setting, as a
52    /// real connection would carry it.
53    tls: bool,
54}
55
56/// Why a request answered with the error path: the classified failure the
57/// handler raised, and whether the application's `on_error` produced the
58/// response.
59///
60/// The handler attaches it to the response as an `http::Extensions`
61/// value. Hyper never serializes extensions, so a real client receives
62/// exactly the bytes it always did; [`TestClient`] lifts it into
63/// [`TestResponse::error`], which is how `nitr test` explains a `500`
64/// without dev mode.
65#[derive(Debug, Clone)]
66pub struct HandlerFailure {
67    /// The classified error: kind, message, source, line, traceback.
68    pub info: ErrorInfo,
69    /// Whether the app's `on_error` handled it.
70    pub handled: bool,
71}
72
73/// A fully collected response from [`TestClient::request`].
74#[derive(Debug)]
75pub struct TestResponse {
76    /// HTTP status code.
77    pub status: u16,
78    /// Header pairs in response order (repeated names appear repeatedly).
79    pub headers: Vec<(String, String)>,
80    /// The collected response body.
81    pub body: Bytes,
82    /// The handler's failure, when the request took the error path.
83    pub error: Option<HandlerFailure>,
84}
85
86impl TestClient {
87    pub(crate) fn new(
88        pool: Arc<RwLock<Arc<RuntimePool>>>,
89        streams: Arc<Semaphore>,
90        protection: Arc<Protection>,
91        tls: bool,
92    ) -> Self {
93        Self {
94            pool,
95            streams,
96            protection,
97            tls,
98        }
99    }
100
101    /// Performs one request through the real dispatch path and collects
102    /// the response (streaming bodies included).
103    pub async fn request(
104        &self,
105        method: &str,
106        path_and_query: &str,
107        headers: &[(String, String)],
108        body: Option<Bytes>,
109    ) -> Result<TestResponse> {
110        self.send(TestRequest {
111            method: method.to_string(),
112            path: path_and_query.to_string(),
113            headers: headers.to_vec(),
114            body,
115            remote_addr: None,
116            timeout: None,
117        })
118        .await
119    }
120
121    /// Performs a [`TestRequest`]: its peer address is what the protection
122    /// layer (the rate limiter above all) sees, and its timeout bounds the
123    /// whole exchange from the client side, body collection included — so
124    /// a stream that never ends fails the test instead of hanging the run.
125    ///
126    /// The exchange runs inside a `request` span shaped like the one the
127    /// live service opens, so log lines carry the request id, method and
128    /// path, and the span's close line is the access-log entry a real
129    /// request would produce.
130    pub async fn send(&self, spec: TestRequest) -> Result<TestResponse> {
131        let method: Method =
132            spec.method.to_uppercase().parse().map_err(|_| {
133                Error::Config(format!("invalid test request method `{}`", spec.method))
134            })?;
135        let uri: Uri = spec
136            .path
137            .parse()
138            .map_err(|_| Error::Config(format!("invalid test request path `{}`", spec.path)))?;
139
140        let mut builder = Request::builder().method(method.clone()).uri(uri.clone());
141        for (name, value) in &spec.headers {
142            builder = builder.header(name, value);
143        }
144        let req = builder.body(
145            Full::new(spec.body.unwrap_or_default())
146                .map_err(|never| match never {})
147                .boxed(),
148        )?;
149
150        let id = self.protection.request_id_for_parts(req.headers());
151        let span = tracing::info_span!(
152            "request",
153            id = %id,
154            method = %method,
155            path = %uri.path(),
156            status = tracing::field::Empty,
157        );
158        let peer = spec.remote_addr.unwrap_or_else(|| DEFAULT_PEER.into());
159        let mut req = LuaRequest::synthetic(req, peer, id.into());
160        req.tls = self.tls;
161
162        let pool = current_pool(&self.pool);
163        let streams = self.streams.clone();
164        let protection = self.protection.clone();
165        let exchange = async move {
166            let resp = handler::handle(&pool, req, streams, protection).await?;
167            collect(resp).await
168        }
169        .instrument(span);
170        match spec.timeout {
171            None => exchange.await,
172            Some(limit) => tokio::time::timeout(limit, exchange).await.map_err(|_| {
173                Error::Script(format!(
174                    "the test request {method} {} did not complete within {} s (its \
175                         `timeout` option); a streaming body that never ends?",
176                    uri.path(),
177                    limit.as_secs_f64()
178                ))
179            })?,
180        }
181    }
182}
183
184/// Reads a response into a [`TestResponse`].
185async fn collect(resp: handler::HttpResponse) -> Result<TestResponse> {
186    let status = resp.status().as_u16();
187    let error = resp.extensions().get::<HandlerFailure>().cloned();
188    let headers = resp
189        .headers()
190        .iter()
191        .map(|(k, v)| {
192            (
193                k.as_str().to_string(),
194                v.to_str().unwrap_or_default().to_string(),
195            )
196        })
197        .collect();
198    let body = match resp.into_body().collect().await {
199        Ok(collected) => collected.to_bytes(),
200        // The response body error type is Infallible.
201        Err(never) => match never {},
202    };
203    Ok(TestResponse {
204        status,
205        headers,
206        body,
207        error,
208    })
209}
210
211impl TestResponse {
212    /// The first value of a (case-insensitive) header, if present.
213    pub fn header(&self, name: &str) -> Option<&str> {
214        self.headers
215            .iter()
216            .find(|(k, _)| k.eq_ignore_ascii_case(name))
217            .map(|(_, v)| v.as_str())
218    }
219}
220
221/// Resolves a fixture file a test names (`t.db.seed("fixtures/x.sql")`)
222/// under `root`, the tests directory: the static server's lexical rule
223/// (no `..`, no absolute path, no NUL), then canonical containment, and
224/// it must be a regular file.
225///
226/// # Errors
227///
228/// A path that could name something outside `root`, or that is not a
229/// regular file there.
230pub fn fixture_path(root: &Path, rel: &str) -> Result<PathBuf> {
231    let refuse = |why: &str| {
232        Error::Script(format!(
233            "fixture `{rel}` {why}: fixtures are regular files under [testing] dir {}",
234            root.display()
235        ))
236    };
237    let joined =
238        crate::safe_path::safe_join(root, rel).map_err(|_| refuse("is not a relative path"))?;
239    let (Ok(canonical), Ok(root_canonical)) = (joined.canonicalize(), root.canonicalize()) else {
240        return Err(refuse("does not exist"));
241    };
242    if !canonical.starts_with(&root_canonical) {
243        return Err(refuse("resolves outside the tests directory"));
244    }
245    if !canonical.is_file() {
246        return Err(refuse("is not a regular file"));
247    }
248    Ok(canonical)
249}
250
251/// Keeps the `nitr test --watch` watcher alive; dropping it stops the
252/// watcher thread.
253pub struct TestWatch {
254    _guard: crate::watch::WatchGuard,
255}
256
257/// Watches what `nitr dev` watches (the handler's directory, the
258/// configuration script, the templates) plus `extra` (the tests
259/// directory), sending on `changed` after each debounced burst of changes
260/// to a Lua source or a template. `None` when there is nothing to watch
261/// or the platform watcher is unavailable.
262pub fn watch_tests(
263    cfg: &crate::Config,
264    extra: &[PathBuf],
265    changed: tokio::sync::mpsc::Sender<()>,
266) -> Option<TestWatch> {
267    crate::watch::spawn(cfg, extra, changed).map(|guard| TestWatch { _guard: guard })
268}
269
270/// Parses a `remote_addr` option: an IP, or an `ip:port`.
271pub(crate) fn parse_peer(text: &str) -> Option<SocketAddr> {
272    text.parse::<SocketAddr>().ok().or_else(|| {
273        text.parse::<std::net::IpAddr>()
274            .ok()
275            .map(|ip| SocketAddr::new(ip, 0))
276    })
277}
278
279/// A duration option in seconds (`timeout = 5`): finite, positive, and at
280/// most a day — `Duration::from_secs_f64` would panic on the rest.
281pub(crate) fn seconds(name: &str, secs: f64) -> mlua::Result<Duration> {
282    Duration::try_from_secs_f64(secs)
283        .ok()
284        .filter(|d| !d.is_zero() && *d <= Duration::from_secs(86_400))
285        .ok_or_else(|| {
286            mlua::Error::RuntimeError(format!(
287                "`{name}` must be a number of seconds between 0 and 86400, got {secs}"
288            ))
289        })
290}
291
292#[cfg(test)]
293mod tests;