tez 0.0.0

A lightweight, ergonomic, and fast high-level HTTP client for Rust
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
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
use std::{fmt, net::SocketAddr, time::Duration};

use http::{HeaderMap, StatusCode, Version};
#[cfg(feature = "json")]
use serde::de::DeserializeOwned;
use tokio::time::Instant;
use url::Url;

use crate::{Body, Error, ErrorKind, Result, redact::SanitizedUrl};

/// Default maximum decoded size collected by response convenience methods.
pub(crate) const DEFAULT_BODY_LIMIT: usize = 16 * 1024 * 1024;

/// Owned HTTP response whose body may still be streaming.
///
/// A client returns this value as soon as final response headers are available.
/// Every valid final status, including `4xx` and `5xx`, is represented as a
/// successful `Response`; interim `1xx` responses are handled internally.
pub struct Response {
    status: StatusCode,
    version: Version,
    headers: HeaderMap,
    effective_url: Url,
    redirect_count: u32,
    remote_addr: Option<SocketAddr>,
    body: Body,
    body_limit: usize,
}

#[derive(Default)]
pub(crate) struct ResponseBuilder {
    status: Option<StatusCode>,
    version: Option<Version>,
    headers: HeaderMap,
    effective_url: Option<Url>,
    remote_addr: Option<SocketAddr>,
    body: Body,
}

impl Response {
    pub(crate) fn builder() -> ResponseBuilder {
        ResponseBuilder::default()
    }

    /// Returns the response status code.
    #[must_use]
    pub fn status(&self) -> StatusCode {
        self.status
    }

    /// Returns the negotiated HTTP version.
    #[must_use]
    pub fn version(&self) -> Version {
        self.version
    }

    /// Returns the response headers.
    #[must_use]
    pub fn headers(&self) -> &HeaderMap {
        &self.headers
    }

    /// Returns mutable response headers.
    #[must_use]
    pub fn headers_mut(&mut self) -> &mut HeaderMap {
        &mut self.headers
    }

    /// Returns the final URL associated with this response.
    #[must_use]
    pub fn effective_url(&self) -> &Url {
        &self.effective_url
    }

    /// Returns the number of redirects followed before this response.
    #[must_use]
    pub fn redirect_count(&self) -> u32 {
        self.redirect_count
    }

    /// Returns the connection's peer address, when available.
    #[must_use]
    pub fn remote_addr(&self) -> Option<SocketAddr> {
        self.remote_addr
    }

    /// Returns the response body.
    #[must_use]
    pub fn body(&self) -> &Body {
        &self.body
    }

    /// Returns mutable access to the response body stream.
    #[must_use]
    pub fn body_mut(&mut self) -> &mut Body {
        &mut self.body
    }

    /// Consumes the response and returns its body without buffering it.
    #[must_use]
    pub fn into_body(self) -> Body {
        self.body
    }

    /// Returns body trailers after the stream reaches EOF.
    #[must_use]
    pub fn trailers(&self) -> Option<&HeaderMap> {
        self.body.trailers()
    }

    /// Collects the decoded body up to the configured limit.
    ///
    /// # Errors
    ///
    /// Returns an error for stream failures, timeouts, or when the decoded
    /// body is larger than the body limit.
    pub async fn collect(mut self) -> Result<Self> {
        self.body = self.body.collect_limited(self.body_limit).await?;
        Ok(self)
    }

    /// Collects and returns decoded body bytes up to the configured limit.
    ///
    /// # Errors
    ///
    /// Returns an error for stream failures, timeouts, or size-limit failures.
    pub async fn bytes(self) -> Result<Vec<u8>> {
        let response = self.collect().await?;
        response
            .body
            .into_buffered_bytes()
            .ok_or_else(|| Error::new(ErrorKind::BodyIo, "body did not become buffered"))
    }

    /// Collects and decodes the body as UTF-8 text.
    ///
    /// # Errors
    ///
    /// Returns an error for body failures or invalid UTF-8.
    pub async fn text(self) -> Result<String> {
        String::from_utf8(self.bytes().await?)
            .map_err(|_| Error::new(ErrorKind::Decoding, "response body is not valid UTF-8"))
    }

    /// Collects and deserializes a JSON response body.
    ///
    /// # Errors
    ///
    /// Returns an error for body failures or invalid JSON.
    #[cfg(feature = "json")]
    pub async fn json<T>(self) -> Result<T>
    where
        T: DeserializeOwned,
    {
        serde_json::from_slice(&self.bytes().await?)
            .map_err(|_| Error::new(ErrorKind::Decoding, "response JSON could not be decoded"))
    }

    /// Drains the decoded body up to the configured body limit.
    ///
    /// Reading to EOF permits connection reuse. If the limit or a deadline is
    /// reached, the remaining body is cancelled by dropping it.
    ///
    /// # Errors
    ///
    /// Returns an error for stream, timeout, or limit failures.
    pub async fn discard(self) -> Result<()> {
        self.body.discard_limited(self.body_limit).await
    }

    pub(crate) fn set_redirect_count(&mut self, count: u32) {
        self.redirect_count = count;
    }

    pub(crate) fn enforce_body_timeouts(&mut self, deadline: Instant, read_idle: Duration) {
        self.body = std::mem::take(&mut self.body).enforce_timeouts(deadline, read_idle);
    }

    pub(crate) fn set_body_limit(&mut self, limit: usize) {
        self.body_limit = limit;
    }

    pub(crate) async fn discard_for_redirect(self, limit: usize) -> Result<()> {
        self.body.discard_limited(limit).await
    }
}

impl ResponseBuilder {
    #[must_use]
    pub(crate) fn status(mut self, status: StatusCode) -> Self {
        self.status = Some(status);
        self
    }

    #[must_use]
    pub(crate) fn version(mut self, version: Version) -> Self {
        self.version = Some(version);
        self
    }

    #[must_use]
    pub(crate) fn headers(mut self, headers: HeaderMap) -> Self {
        self.headers.extend(headers);
        self
    }

    #[must_use]
    pub(crate) fn effective_url(mut self, url: Url) -> Self {
        self.effective_url = Some(url);
        self
    }

    #[must_use]
    pub(crate) fn remote_addr(mut self, address: SocketAddr) -> Self {
        self.remote_addr = Some(address);
        self
    }

    #[must_use]
    pub(crate) fn body(mut self, body: impl Into<Body>) -> Self {
        self.body = body.into();
        self
    }

    pub(crate) fn build(self) -> Result<Response> {
        let status = self
            .status
            .ok_or(Error::invalid_response("response status is required"))?;
        let version = self
            .version
            .ok_or(Error::invalid_response("response HTTP version is required"))?;
        let effective_url = self
            .effective_url
            .ok_or(Error::invalid_response("response URL is required"))?;
        if !matches!(effective_url.scheme(), "http" | "https")
            || effective_url.host_str().is_none()
            || !effective_url.username().is_empty()
            || effective_url.password().is_some()
            || effective_url.fragment().is_some()
        {
            return Err(Error::invalid_response(
                "response URL must be an absolute HTTP URL without userinfo or a fragment",
            ));
        }
        Ok(Response {
            status,
            version,
            headers: self.headers,
            effective_url,
            redirect_count: 0,
            remote_addr: self.remote_addr,
            body: self.body,
            body_limit: DEFAULT_BODY_LIMIT,
        })
    }
}

impl fmt::Debug for Response {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Response")
            .field("status", &self.status)
            .field("version", &self.version)
            .field("header_count", &self.headers.len())
            .field("effective_url", &SanitizedUrl(&self.effective_url))
            .field("redirect_count", &self.redirect_count)
            .field("remote_addr", &self.remote_addr)
            .field("body", &self.body)
            .finish()
    }
}

impl fmt::Debug for ResponseBuilder {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ResponseBuilder")
            .field("status", &self.status)
            .field("version", &self.version)
            .field("header_count", &self.headers.len())
            .field("has_effective_url", &self.effective_url.is_some())
            .field("body", &self.body)
            .finish()
    }
}

#[cfg(test)]
mod describe_response {
    use http::HeaderValue;
    #[cfg(feature = "json")]
    use http::header::CONTENT_TYPE;

    use super::*;

    fn response(body: impl Into<Body>) -> Response {
        Response::builder()
            .status(StatusCode::OK)
            .version(Version::HTTP_11)
            .effective_url(Url::parse("https://example.com/path?token=secret").unwrap())
            .body(body)
            .build()
            .unwrap()
    }

    #[test]
    fn it_custom_response_requires_status_version_and_url() {
        assert_eq!(
            Response::builder().build().unwrap_err().to_string(),
            "invalid response: response status is required"
        );
        assert_eq!(
            Response::builder()
                .status(StatusCode::OK)
                .version(Version::HTTP_11)
                .build()
                .unwrap_err()
                .to_string(),
            "invalid response: response URL is required"
        );
        assert_eq!(
            Response::builder()
                .status(StatusCode::OK)
                .effective_url(Url::parse("https://example.com").unwrap())
                .build()
                .unwrap_err()
                .to_string(),
            "invalid response: response HTTP version is required"
        );
        for url in [
            "file:///tmp/value",
            "https://user:pass@example.com/",
            "https://example.com/#fragment",
        ] {
            assert!(
                Response::builder()
                    .status(StatusCode::OK)
                    .version(Version::HTTP_11)
                    .effective_url(Url::parse(url).unwrap())
                    .build()
                    .is_err()
            );
        }
    }

    #[test]
    fn it_custom_response_uses_neutral_policy_defaults() {
        let response = response(Body::empty());

        assert_eq!(response.redirect_count, 0);
        assert_eq!(response.body_limit, DEFAULT_BODY_LIMIT);
    }

    #[test]
    fn it_response_builder_headers_replace_matching_names_and_preserve_repeated_values() {
        let mut initial = HeaderMap::new();
        initial.append("x-mode", HeaderValue::from_static("old-first"));
        initial.append("x-mode", HeaderValue::from_static("old-second"));
        initial.insert("x-stable", HeaderValue::from_static("kept"));
        let mut replacement = HeaderMap::new();
        replacement.append("x-mode", HeaderValue::from_static("new-first"));
        replacement.append("x-mode", HeaderValue::from_static("new-second"));

        let response = Response::builder()
            .status(StatusCode::OK)
            .version(Version::HTTP_11)
            .effective_url(Url::parse("https://example.com").unwrap())
            .headers(initial)
            .headers(replacement)
            .build()
            .unwrap();
        let values = response
            .headers()
            .get_all("x-mode")
            .iter()
            .map(|value| value.to_str().unwrap())
            .collect::<Vec<_>>();

        assert_eq!(values, ["new-first", "new-second"]);
        assert_eq!(response.headers()["x-stable"], "kept");
    }

    #[tokio::test]
    async fn it_collection_is_bounded_and_exact_at_limit() {
        let exact = response("four");
        assert_eq!(
            exact.collect().await.unwrap().body().as_bytes().unwrap(),
            b"four"
        );

        let mut over = Response::builder()
            .status(StatusCode::OK)
            .version(Version::HTTP_11)
            .effective_url(Url::parse("https://example.com").unwrap())
            .body("fives")
            .build()
            .unwrap();
        over.set_body_limit(4);
        assert_eq!(over.bytes().await.unwrap_err().kind(), ErrorKind::BodyLimit);
    }

    #[tokio::test]
    async fn it_collect_preserves_response_metadata_while_buffering_body() {
        let effective_url = Url::parse("https://example.com/final?secret=hidden").unwrap();
        let remote_addr = "127.0.0.1:443".parse().unwrap();
        let mut headers = HeaderMap::new();
        headers.insert("x-response", HeaderValue::from_static("preserved"));
        let mut response = Response::builder()
            .status(StatusCode::CREATED)
            .version(Version::HTTP_2)
            .headers(headers)
            .effective_url(effective_url.clone())
            .remote_addr(remote_addr)
            .body("four")
            .build()
            .unwrap();
        response.set_redirect_count(2);
        response.set_body_limit(4);

        let response = response.collect().await.unwrap();

        assert_eq!(response.status(), StatusCode::CREATED);
        assert_eq!(response.version(), Version::HTTP_2);
        assert_eq!(response.headers()["x-response"], "preserved");
        assert_eq!(response.effective_url(), &effective_url);
        assert_eq!(response.redirect_count(), 2);
        assert_eq!(response.remote_addr(), Some(remote_addr));
        assert_eq!(response.body().as_bytes(), Some(&b"four"[..]));
    }

    #[cfg(feature = "json")]
    #[tokio::test]
    async fn it_json_collects_before_decoding() {
        let mut headers = HeaderMap::new();
        headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
        let value: serde_json::Value = Response::builder()
            .status(StatusCode::OK)
            .version(Version::HTTP_11)
            .effective_url(Url::parse("https://example.com").unwrap())
            .headers(headers)
            .body(r#"{"ok":true}"#)
            .build()
            .unwrap()
            .json()
            .await
            .unwrap();

        assert_eq!(value, serde_json::json!({ "ok": true }));
    }

    #[test]
    fn it_response_debug_redacts_url_query_headers_and_body() {
        let mut headers = HeaderMap::new();
        headers.insert("authorization", HeaderValue::from_static("secret-token"));
        let response = Response::builder()
            .status(StatusCode::OK)
            .version(Version::HTTP_11)
            .effective_url(Url::parse("https://example.com/path?token=query-secret").unwrap())
            .headers(headers)
            .body("body-secret")
            .build()
            .unwrap();
        let debug = format!("{response:?}");

        for secret in ["query-secret", "secret-token", "body-secret"] {
            assert!(!debug.contains(secret), "debug leaked {secret}: {debug}");
        }
    }
}