curl_rest/
lib.rs

1//! A small, blocking REST client built on libcurl.
2//!
3//! The API is a builder centered around `Client`, with GET as the default method.
4//! Use `send` as the terminal operation.
5//!
6//! # libcurl dependency
7//! `curl-rest` links to libcurl, so your build needs a libcurl development
8//! package available on the system (for example, installed via your OS package
9//! manager). If you prefer a vendored build or static linking, enable the
10//! appropriate `curl`/`curl-sys` features in your application so Cargo
11//! propagates them to this crate.
12//!
13//! This crate exposes a few convenience features (default is `ssl`):
14//! - `ssl`: enable OpenSSL-backed TLS (libcurl's default).
15//! - `rustls`: enable Rustls-backed TLS (disable default features in your
16//!   dependency to avoid OpenSSL).
17//! - `static-curl`: build and link against a bundled libcurl.
18//! - `static-ssl`: build and link against a bundled OpenSSL.
19//! - `vendored`: enables both `static-curl` and `static-ssl`.
20//!
21//! # Quickstart
22//! ```no_run
23//! let resp = curl_rest::get("https://example.com")?;
24//! println!("Status: {}", resp.status);
25//!
26//! let resp = curl_rest::Client::default()
27//!     .post()
28//!     .body_json(r#"{"name":"stanley"}"#)
29//!     .send("https://example.com/users")?;
30//! println!("{}", String::from_utf8_lossy(&resp.body));
31//! # Ok::<(), curl_rest::Error>(())
32//! ```
33//!
34//! # Examples
35//! ```no_run
36//! let resp = curl_rest::Client::default()
37//!     .get()
38//!     .header(curl_rest::Header::Accept("application/json".into()))
39//!     .header(curl_rest::Header::Custom("X-Request-Id".into(), "req-123".into()))
40//!     .query_param_kv("page", "1")
41//!     .send("https://example.com/api/users")
42//!     .expect("request failed");
43//! println!("Status: {}", resp.status);
44//! ```
45
46use curl::easy::{Easy2, Handler, List, WriteError};
47use percent_encoding::{NON_ALPHANUMERIC, utf8_percent_encode};
48use std::borrow::Cow;
49use thiserror::Error;
50use url::Url;
51
52/// HTTP response container returned by `send`.
53pub struct Response {
54    /// Status code returned by the server.
55    pub status: StatusCode,
56    /// Raw response body bytes.
57    pub body: Vec<u8>,
58}
59
60macro_rules! status_codes {
61    ($(
62        $variant:ident => ($code:literal, $reason:literal, $const_name:ident)
63    ),+ $(,)?) => {
64        /// HTTP status codes defined by RFC 9110 and related specifications.
65        #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
66        #[repr(u16)]
67        pub enum StatusCode {
68            $(
69                #[doc = $reason]
70                $variant = $code,
71            )+
72        }
73
74        impl StatusCode {
75            /// Returns the numeric status code.
76            pub const fn as_u16(self) -> u16 {
77                self as u16
78            }
79
80            /// Returns the canonical reason phrase for this status code.
81            pub const fn canonical_reason(self) -> &'static str {
82                match self {
83                    $(StatusCode::$variant => $reason,)+
84                }
85            }
86
87            /// Converts a numeric status code into a `StatusCode` if known.
88            pub const fn from_u16(code: u16) -> Option<Self> {
89                match code {
90                    $($code => Some(StatusCode::$variant),)+
91                    _ => None,
92                }
93            }
94
95            $(
96                /// Alias matching reqwest's naming style.
97                pub const $const_name: StatusCode = StatusCode::$variant;
98            )+
99        }
100
101        impl std::fmt::Display for StatusCode {
102            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
103                write!(f, "{} {}", self.as_u16(), self.canonical_reason())
104            }
105        }
106    };
107}
108
109status_codes! {
110    Continue => (100, "Continue", CONTINUE),
111    SwitchingProtocols => (101, "Switching Protocols", SWITCHING_PROTOCOLS),
112    Processing => (102, "Processing", PROCESSING),
113    EarlyHints => (103, "Early Hints", EARLY_HINTS),
114    Ok => (200, "OK", OK),
115    Created => (201, "Created", CREATED),
116    Accepted => (202, "Accepted", ACCEPTED),
117    NonAuthoritativeInformation => (203, "Non-Authoritative Information", NON_AUTHORITATIVE_INFORMATION),
118    NoContent => (204, "No Content", NO_CONTENT),
119    ResetContent => (205, "Reset Content", RESET_CONTENT),
120    PartialContent => (206, "Partial Content", PARTIAL_CONTENT),
121    MultiStatus => (207, "Multi-Status", MULTI_STATUS),
122    AlreadyReported => (208, "Already Reported", ALREADY_REPORTED),
123    ImUsed => (226, "IM Used", IM_USED),
124    MultipleChoices => (300, "Multiple Choices", MULTIPLE_CHOICES),
125    MovedPermanently => (301, "Moved Permanently", MOVED_PERMANENTLY),
126    Found => (302, "Found", FOUND),
127    SeeOther => (303, "See Other", SEE_OTHER),
128    NotModified => (304, "Not Modified", NOT_MODIFIED),
129    UseProxy => (305, "Use Proxy", USE_PROXY),
130    TemporaryRedirect => (307, "Temporary Redirect", TEMPORARY_REDIRECT),
131    PermanentRedirect => (308, "Permanent Redirect", PERMANENT_REDIRECT),
132    BadRequest => (400, "Bad Request", BAD_REQUEST),
133    Unauthorized => (401, "Unauthorized", UNAUTHORIZED),
134    PaymentRequired => (402, "Payment Required", PAYMENT_REQUIRED),
135    Forbidden => (403, "Forbidden", FORBIDDEN),
136    NotFound => (404, "Not Found", NOT_FOUND),
137    MethodNotAllowed => (405, "Method Not Allowed", METHOD_NOT_ALLOWED),
138    NotAcceptable => (406, "Not Acceptable", NOT_ACCEPTABLE),
139    ProxyAuthenticationRequired => (407, "Proxy Authentication Required", PROXY_AUTHENTICATION_REQUIRED),
140    RequestTimeout => (408, "Request Timeout", REQUEST_TIMEOUT),
141    Conflict => (409, "Conflict", CONFLICT),
142    Gone => (410, "Gone", GONE),
143    LengthRequired => (411, "Length Required", LENGTH_REQUIRED),
144    PreconditionFailed => (412, "Precondition Failed", PRECONDITION_FAILED),
145    PayloadTooLarge => (413, "Content Too Large", PAYLOAD_TOO_LARGE),
146    UriTooLong => (414, "URI Too Long", URI_TOO_LONG),
147    UnsupportedMediaType => (415, "Unsupported Media Type", UNSUPPORTED_MEDIA_TYPE),
148    RangeNotSatisfiable => (416, "Range Not Satisfiable", RANGE_NOT_SATISFIABLE),
149    ExpectationFailed => (417, "Expectation Failed", EXPECTATION_FAILED),
150    ImATeapot => (418, "I'm a teapot", IM_A_TEAPOT),
151    MisdirectedRequest => (421, "Misdirected Request", MISDIRECTED_REQUEST),
152    UnprocessableEntity => (422, "Unprocessable Content", UNPROCESSABLE_ENTITY),
153    Locked => (423, "Locked", LOCKED),
154    FailedDependency => (424, "Failed Dependency", FAILED_DEPENDENCY),
155    TooEarly => (425, "Too Early", TOO_EARLY),
156    UpgradeRequired => (426, "Upgrade Required", UPGRADE_REQUIRED),
157    PreconditionRequired => (428, "Precondition Required", PRECONDITION_REQUIRED),
158    TooManyRequests => (429, "Too Many Requests", TOO_MANY_REQUESTS),
159    RequestHeaderFieldsTooLarge => (431, "Request Header Fields Too Large", REQUEST_HEADER_FIELDS_TOO_LARGE),
160    UnavailableForLegalReasons => (451, "Unavailable For Legal Reasons", UNAVAILABLE_FOR_LEGAL_REASONS),
161    InternalServerError => (500, "Internal Server Error", INTERNAL_SERVER_ERROR),
162    NotImplemented => (501, "Not Implemented", NOT_IMPLEMENTED),
163    BadGateway => (502, "Bad Gateway", BAD_GATEWAY),
164    ServiceUnavailable => (503, "Service Unavailable", SERVICE_UNAVAILABLE),
165    GatewayTimeout => (504, "Gateway Timeout", GATEWAY_TIMEOUT),
166    HttpVersionNotSupported => (505, "HTTP Version Not Supported", HTTP_VERSION_NOT_SUPPORTED),
167    VariantAlsoNegotiates => (506, "Variant Also Negotiates", VARIANT_ALSO_NEGOTIATES),
168    InsufficientStorage => (507, "Insufficient Storage", INSUFFICIENT_STORAGE),
169    LoopDetected => (508, "Loop Detected", LOOP_DETECTED),
170    NotExtended => (510, "Not Extended", NOT_EXTENDED),
171    NetworkAuthenticationRequired => (511, "Network Authentication Required", NETWORK_AUTHENTICATION_REQUIRED),
172}
173
174/// Error type returned by the curl-rest client.
175#[derive(Debug, Error)]
176pub enum Error {
177    /// Error reported by libcurl.
178    #[error("curl error: {0}")]
179    Client(#[from] curl::Error),
180    /// The provided URL could not be parsed.
181    #[error("invalid url: {0}")]
182    InvalidUrl(String),
183    /// The provided header value contained invalid characters.
184    #[error("invalid header value for {0}")]
185    InvalidHeaderValue(String),
186    /// The provided header name contained invalid characters.
187    #[error("invalid header name: {0}")]
188    InvalidHeaderName(String),
189    /// The server returned an unrecognized HTTP status code.
190    #[error("invalid HTTP status code: {0}")]
191    InvalidStatusCode(u32),
192}
193
194/// Common HTTP headers supported by the client, plus `Custom` for non-standard names.
195#[derive(Clone)]
196pub enum Header<'a> {
197    /// Authorization header, e.g. "Bearer &lt;token&gt;".
198    Authorization(Cow<'a, str>),
199    /// Accept header describing accepted response types.
200    Accept(Cow<'a, str>),
201    /// Content-Type header describing request body type.
202    ContentType(Cow<'a, str>),
203    /// User-Agent header string.
204    UserAgent(Cow<'a, str>),
205    /// Accept-Encoding header for compression preferences.
206    ///
207    /// Common values include `gzip`, `br`, or `deflate`.
208    AcceptEncoding(Cow<'a, str>),
209    /// Accept-Language header for locale preferences.
210    AcceptLanguage(Cow<'a, str>),
211    /// Cache-Control header directives.
212    CacheControl(Cow<'a, str>),
213    /// Referer header.
214    Referer(Cow<'a, str>),
215    /// Origin header.
216    Origin(Cow<'a, str>),
217    /// Host header.
218    Host(Cow<'a, str>),
219    /// Custom header for non-standard names like "X-Request-Id".
220    ///
221    /// Header names must be valid RFC 9110 `token` values (tchar only).
222    Custom(Cow<'a, str>, Cow<'a, str>),
223}
224
225/// Query parameter represented as a key-value pair.
226#[derive(Clone)]
227pub struct QueryParam<'a> {
228    key: Cow<'a, str>,
229    value: Cow<'a, str>,
230}
231
232/// Supported HTTP methods.
233pub enum Method {
234    /// HTTP GET.
235    Get,
236    /// HTTP POST.
237    Post,
238    /// HTTP PUT.
239    Put,
240    /// HTTP DELETE.
241    Delete,
242    /// HTTP HEAD.
243    Head,
244    /// HTTP OPTIONS.
245    Options,
246    /// HTTP PATCH.
247    Patch,
248    /// HTTP CONNECT.
249    Connect,
250    /// HTTP TRACE.
251    Trace,
252}
253
254struct Collector(Vec<u8>);
255
256impl Handler for Collector {
257    fn write(&mut self, data: &[u8]) -> Result<usize, WriteError> {
258        self.0.extend_from_slice(data);
259        Ok(data.len())
260    }
261}
262
263/// Builder for constructing and sending a blocking HTTP request.
264///
265/// Defaults to GET when created via `Default`.
266pub struct Client<'a> {
267    method: Method,
268    headers: Vec<Header<'a>>,
269    query: Vec<QueryParam<'a>>,
270    body: Option<Body<'a>>,
271    default_user_agent: Option<Cow<'a, str>>,
272}
273
274#[deprecated(note = "Renamed to Client; use Client instead.")]
275pub type Curl<'a> = Client<'a>;
276
277impl<'a> Default for Client<'a> {
278    fn default() -> Self {
279        Self {
280            method: Method::Get,
281            headers: Vec::new(),
282            query: Vec::new(),
283            body: None,
284            default_user_agent: None,
285        }
286    }
287}
288
289impl<'a> Client<'a> {
290    /// Creates a new builder with default settings (GET, no headers, no query).
291    pub fn new() -> Self {
292        Self::default()
293    }
294
295    /// Creates a new builder with a default User-Agent header.
296    ///
297    /// The User-Agent is only applied if the request does not already set one.
298    pub fn with_user_agent(agent: impl Into<Cow<'a, str>>) -> Self {
299        Self {
300            default_user_agent: Some(agent.into()),
301            ..Self::default()
302        }
303    }
304
305    /// Sets the HTTP method explicitly.
306    pub fn method(mut self, method: Method) -> Self {
307        self.method = method;
308        self
309    }
310
311    /// Sets the request method to GET.
312    pub fn get(self) -> Self {
313        self.method(Method::Get)
314    }
315
316    /// Sets the request method to POST.
317    pub fn post(self) -> Self {
318        self.method(Method::Post)
319    }
320
321    /// Sets the request method to PUT.
322    pub fn put(self) -> Self {
323        self.method(Method::Put)
324    }
325
326    /// Sets the request method to DELETE.
327    pub fn delete(self) -> Self {
328        self.method(Method::Delete)
329    }
330
331    /// Sets the request method to HEAD.
332    pub fn head(self) -> Self {
333        self.method(Method::Head)
334    }
335
336    /// Sets the request method to OPTIONS.
337    pub fn options(self) -> Self {
338        self.method(Method::Options)
339    }
340
341    /// Sets the request method to PATCH.
342    pub fn patch(self) -> Self {
343        self.method(Method::Patch)
344    }
345
346    /// Sets the request method to CONNECT.
347    pub fn connect(self) -> Self {
348        self.method(Method::Connect)
349    }
350
351    /// Sets the request method to TRACE.
352    pub fn trace(self) -> Self {
353        self.method(Method::Trace)
354    }
355
356    /// Adds a single header.
357    ///
358    /// # Examples
359    /// ```no_run
360    /// let resp = curl_rest::Client::default()
361    ///     .get()
362    ///     .header(curl_rest::Header::Authorization("Bearer token".into()))
363    ///     .send("https://example.com/private")?;
364    /// # Ok::<(), curl_rest::Error>(())
365    /// ```
366    ///
367    /// # Errors
368    /// This method does not return errors. Header validation happens in `send`.
369    pub fn header(mut self, header: Header<'a>) -> Self {
370        self.headers.push(header);
371        self
372    }
373
374    /// Adds multiple headers.
375    ///
376    /// # Examples
377    /// ```no_run
378    /// let resp = curl_rest::Client::default()
379    ///     .get()
380    ///     .headers([
381    ///         curl_rest::Header::Accept("application/json".into()),
382    ///         curl_rest::Header::UserAgent("curl-rest/0.1".into()),
383    ///     ])
384    ///     .send("https://example.com/users")?;
385    /// # Ok::<(), curl_rest::Error>(())
386    /// ```
387    ///
388    /// # Errors
389    /// This method does not return errors. Header validation happens in `send`.
390    pub fn headers<I>(mut self, headers: I) -> Self
391    where
392        I: IntoIterator<Item = Header<'a>>,
393    {
394        self.headers.extend(headers);
395        self
396    }
397
398    /// Adds a single query parameter.
399    ///
400    /// # Examples
401    /// ```no_run
402    /// let resp = curl_rest::Client::default()
403    ///     .get()
404    ///     .query_param(curl_rest::QueryParam::new("q", "rust"))
405    ///     .send("https://example.com/search")?;
406    /// # Ok::<(), curl_rest::Error>(())
407    /// ```
408    ///
409    /// # Errors
410    /// This method does not return errors. URL validation happens in `send`.
411    pub fn query_param(mut self, param: QueryParam<'a>) -> Self {
412        self.query.push(param);
413        self
414    }
415
416    /// Adds a single query parameter by key/value.
417    ///
418    /// # Examples
419    /// ```no_run
420    /// let resp = curl_rest::Client::default()
421    ///     .get()
422    ///     .query_param_kv("page", "1")
423    ///     .send("https://example.com/search")?;
424    /// # Ok::<(), curl_rest::Error>(())
425    /// ```
426    ///
427    /// # Errors
428    /// This method does not return errors. URL validation happens in `send`.
429    pub fn query_param_kv(
430        self,
431        key: impl Into<Cow<'a, str>>,
432        value: impl Into<Cow<'a, str>>,
433    ) -> Self {
434        self.query_param(QueryParam::new(key, value))
435    }
436
437    /// Adds multiple query parameters.
438    ///
439    /// # Examples
440    /// ```no_run
441    /// let resp = curl_rest::Client::default()
442    ///     .get()
443    ///     .query_params([
444    ///         curl_rest::QueryParam::new("sort", "desc"),
445    ///         curl_rest::QueryParam::new("limit", "50"),
446    ///     ])
447    ///     .send("https://example.com/items")?;
448    /// # Ok::<(), curl_rest::Error>(())
449    /// ```
450    ///
451    /// # Errors
452    /// This method does not return errors. URL validation happens in `send`.
453    pub fn query_params<I>(mut self, params: I) -> Self
454    where
455        I: IntoIterator<Item = QueryParam<'a>>,
456    {
457        self.query.extend(params);
458        self
459    }
460
461    /// Sets a request body explicitly.
462    ///
463    /// # Examples
464    /// ```no_run
465    /// let resp = curl_rest::Client::default()
466    ///     .post()
467    ///     .body(curl_rest::Body::Text("hello".into()))
468    ///     .send("https://example.com/echo")?;
469    /// # Ok::<(), curl_rest::Error>(())
470    /// ```
471    ///
472    /// # Errors
473    /// This method does not return errors. Failures are reported by `send`.
474    pub fn body(mut self, body: Body<'a>) -> Self {
475        self.body = Some(body);
476        self
477    }
478
479    /// Sets a raw byte body.
480    ///
481    /// # Examples
482    /// ```no_run
483    /// let resp = curl_rest::Client::default()
484    ///     .post()
485    ///     .body_bytes(vec![1, 2, 3])
486    ///     .send("https://example.com/bytes")?;
487    /// # Ok::<(), curl_rest::Error>(())
488    /// ```
489    ///
490    /// # Errors
491    /// This method does not return errors. Failures are reported by `send`.
492    pub fn body_bytes(self, bytes: impl Into<Cow<'a, [u8]>>) -> Self {
493        self.body(Body::Bytes(bytes.into()))
494    }
495
496    /// Sets a text body with a `text/plain; charset=utf-8` default content type.
497    ///
498    /// # Examples
499    /// ```no_run
500    /// let resp = curl_rest::Client::default()
501    ///     .post()
502    ///     .body_text("hello")
503    ///     .send("https://example.com/echo")?;
504    /// # Ok::<(), curl_rest::Error>(())
505    /// ```
506    ///
507    /// # Errors
508    /// This method does not return errors. Failures are reported by `send`.
509    pub fn body_text(self, text: impl Into<Cow<'a, str>>) -> Self {
510        self.body(Body::Text(text.into()))
511    }
512
513    /// Sets a JSON body with an `application/json` default content type.
514    ///
515    /// # Examples
516    /// ```no_run
517    /// let resp = curl_rest::Client::default()
518    ///     .post()
519    ///     .body_json(r#"{"name":"stanley"}"#)
520    ///     .send("https://example.com/users")?;
521    /// # Ok::<(), curl_rest::Error>(())
522    /// ```
523    ///
524    /// # Errors
525    /// This method does not return errors. Failures are reported by `send`.
526    pub fn body_json(self, json: impl Into<Cow<'a, str>>) -> Self {
527        self.body(Body::Json(json.into()))
528    }
529
530    /// Sends the request to the provided URL.
531    ///
532    /// # Errors
533    /// Returns an error if the URL is invalid, a header name or value is malformed, the
534    /// status code is unrecognized, or libcurl reports a failure.
535    pub fn send(self, url: &str) -> Result<Response, Error> {
536        let mut easy = Easy2::new(Collector(Vec::new()));
537        self.method.apply(&mut easy)?;
538        let mut list = List::new();
539        let mut has_headers = false;
540        for header in &self.headers {
541            list.append(&header.to_line()?)?;
542            has_headers = true;
543        }
544        if let Some(default_user_agent) = &self.default_user_agent {
545            if !self.has_user_agent_header() {
546                list.append(&format!("User-Agent: {default_user_agent}"))?;
547                has_headers = true;
548            }
549        }
550        if let Some(content_type) = self.body_content_type() {
551            if !self.has_content_type_header() {
552                list.append(&format!("Content-Type: {content_type}"))?;
553                has_headers = true;
554            }
555        }
556        if has_headers {
557            easy.http_headers(list)?;
558        }
559        if let Some(body) = &self.body {
560            easy.post_fields_copy(body.bytes())?;
561        }
562        let url = add_query_params(url, &self.query);
563        validate_url(url.as_ref())?;
564        easy.url(url.as_ref())?;
565        easy.perform()?;
566
567        let status_code = easy.response_code()?;
568        let status_u16 =
569            u16::try_from(status_code).map_err(|_| Error::InvalidStatusCode(status_code))?;
570        let status =
571            StatusCode::from_u16(status_u16).ok_or(Error::InvalidStatusCode(status_code))?;
572        let body = easy.get_ref().0.clone();
573        Ok(Response { status, body })
574    }
575
576    fn has_content_type_header(&self) -> bool {
577        self.headers.iter().any(|header| match header {
578            Header::ContentType(_) => true,
579            Header::Custom(name, _) => name.eq_ignore_ascii_case("Content-Type"),
580            _ => false,
581        })
582    }
583
584    fn has_user_agent_header(&self) -> bool {
585        self.headers.iter().any(|header| match header {
586            Header::UserAgent(_) => true,
587            Header::Custom(name, _) => name.eq_ignore_ascii_case("User-Agent"),
588            _ => false,
589        })
590    }
591
592    fn body_content_type(&self) -> Option<&'static str> {
593        match &self.body {
594            Some(Body::Json(_)) => Some("application/json"),
595            Some(Body::Text(_)) => Some("text/plain; charset=utf-8"),
596            Some(Body::Bytes(_)) => None,
597            None => None,
598        }
599    }
600}
601
602impl Method {
603    fn apply(&self, easy: &mut Easy2<Collector>) -> Result<(), Error> {
604        match self {
605            Method::Get => easy.get(true)?,
606            Method::Post => easy.post(true)?,
607            Method::Put => easy.custom_request("PUT")?,
608            Method::Delete => easy.custom_request("DELETE")?,
609            Method::Head => easy.nobody(true)?,
610            Method::Options => easy.custom_request("OPTIONS")?,
611            Method::Patch => easy.custom_request("PATCH")?,
612            Method::Connect => easy.custom_request("CONNECT")?,
613            Method::Trace => easy.custom_request("TRACE")?,
614        }
615        Ok(())
616    }
617}
618
619impl Header<'_> {
620    fn to_line(&self) -> Result<String, Error> {
621        let name = self.name();
622        let value = self.value();
623        if value.contains('\n') || value.contains('\r') {
624            return Err(Error::InvalidHeaderValue(name.to_string()));
625        }
626        if matches!(self, Header::Custom(_, _)) {
627            validate_header_name(name)?;
628        }
629        match self {
630            Header::Authorization(value) => Ok(format!("Authorization: {value}")),
631            Header::Accept(value) => Ok(format!("Accept: {value}")),
632            Header::ContentType(value) => Ok(format!("Content-Type: {value}")),
633            Header::UserAgent(value) => Ok(format!("User-Agent: {value}")),
634            Header::AcceptEncoding(value) => Ok(format!("Accept-Encoding: {value}")),
635            Header::AcceptLanguage(value) => Ok(format!("Accept-Language: {value}")),
636            Header::CacheControl(value) => Ok(format!("Cache-Control: {value}")),
637            Header::Referer(value) => Ok(format!("Referer: {value}")),
638            Header::Origin(value) => Ok(format!("Origin: {value}")),
639            Header::Host(value) => Ok(format!("Host: {value}")),
640            Header::Custom(name, value) => Ok(format!("{}: {}", name, value)),
641        }
642    }
643
644    fn name(&self) -> &str {
645        match self {
646            Header::Authorization(_) => "Authorization",
647            Header::Accept(_) => "Accept",
648            Header::ContentType(_) => "Content-Type",
649            Header::UserAgent(_) => "User-Agent",
650            Header::AcceptEncoding(_) => "Accept-Encoding",
651            Header::AcceptLanguage(_) => "Accept-Language",
652            Header::CacheControl(_) => "Cache-Control",
653            Header::Referer(_) => "Referer",
654            Header::Origin(_) => "Origin",
655            Header::Host(_) => "Host",
656            Header::Custom(name, _) => name.as_ref(),
657        }
658    }
659
660    fn value(&self) -> &str {
661        match self {
662            Header::Authorization(value) => value.as_ref(),
663            Header::Accept(value) => value.as_ref(),
664            Header::ContentType(value) => value.as_ref(),
665            Header::UserAgent(value) => value.as_ref(),
666            Header::AcceptEncoding(value) => value.as_ref(),
667            Header::AcceptLanguage(value) => value.as_ref(),
668            Header::CacheControl(value) => value.as_ref(),
669            Header::Referer(value) => value.as_ref(),
670            Header::Origin(value) => value.as_ref(),
671            Header::Host(value) => value.as_ref(),
672            Header::Custom(_, value) => value.as_ref(),
673        }
674    }
675}
676
677pub enum Body<'a> {
678    /// JSON text body.
679    Json(Cow<'a, str>),
680    /// UTF-8 text body.
681    Text(Cow<'a, str>),
682    /// Raw bytes body.
683    Bytes(Cow<'a, [u8]>),
684}
685
686impl Body<'_> {
687    fn bytes(&self) -> &[u8] {
688        match self {
689            Body::Json(value) => value.as_bytes(),
690            Body::Text(value) => value.as_bytes(),
691            Body::Bytes(value) => value.as_ref(),
692        }
693    }
694}
695
696impl<'a> QueryParam<'a> {
697    /// Creates a new query parameter.
698    ///
699    /// # Examples
700    /// ```no_run
701    /// let resp = curl_rest::Client::default()
702    ///     .get()
703    ///     .query_param(curl_rest::QueryParam::new("page", "2"))
704    ///     .send("https://example.com/search")?;
705    /// # Ok::<(), curl_rest::Error>(())
706    /// ```
707    pub fn new(key: impl Into<Cow<'a, str>>, value: impl Into<Cow<'a, str>>) -> Self {
708        Self {
709            key: key.into(),
710            value: value.into(),
711        }
712    }
713}
714
715fn add_query_params<'a>(url: &'a str, params: &[QueryParam<'_>]) -> Cow<'a, str> {
716    if params.is_empty() {
717        return Cow::Borrowed(url);
718    }
719
720    let (base, fragment) = match url.split_once('#') {
721        Some((base, fragment)) => (base, Some(fragment)),
722        None => (url, None),
723    };
724
725    let mut out = String::with_capacity(base.len() + 1);
726    out.push_str(base);
727
728    if base.contains('?') {
729        if !base.ends_with('?') && !base.ends_with('&') {
730            out.push('&');
731        }
732    } else {
733        out.push('?');
734    }
735
736    for (idx, param) in params.iter().enumerate() {
737        if idx > 0 {
738            out.push('&');
739        }
740        out.push_str(&encode_query_component(param.key.as_ref()));
741        out.push('=');
742        out.push_str(&encode_query_component(param.value.as_ref()));
743    }
744
745    if let Some(fragment) = fragment {
746        out.push('#');
747        out.push_str(fragment);
748    }
749
750    Cow::Owned(out)
751}
752
753fn encode_query_component(value: &str) -> String {
754    utf8_percent_encode(value, NON_ALPHANUMERIC).to_string()
755}
756
757fn validate_url(url: &str) -> Result<(), Error> {
758    Url::parse(url)
759        .map(|_| ())
760        .map_err(|_| Error::InvalidUrl(url.to_string()))
761}
762
763fn validate_header_name(name: &str) -> Result<(), Error> {
764    if name.is_empty() {
765        return Err(Error::InvalidHeaderName(name.to_string()));
766    }
767    for b in name.bytes() {
768        if !is_tchar(b) {
769            return Err(Error::InvalidHeaderName(name.to_string()));
770        }
771    }
772    Ok(())
773}
774
775fn is_tchar(b: u8) -> bool {
776    matches!(
777        b,
778        b'!' | b'#' | b'$' | b'%' | b'&' | b'\'' | b'*' | b'+' | b'-' | b'.' | b'^' | b'_' | b'`'
779            | b'|' | b'~' | b'0'..=b'9' | b'a'..=b'z' | b'A'..=b'Z'
780    )
781}
782
783/// Sends a request with the given method and URL using default builder settings.
784///
785/// # Errors
786/// Returns an error if the URL is invalid, the status code is unrecognized, or
787/// libcurl reports a failure.
788///
789/// # Examples
790/// ```no_run
791/// let resp = curl_rest::request(curl_rest::Method::Get, "https://example.com")?;
792/// println!("Status: {}", resp.status);
793/// # Ok::<(), curl_rest::Error>(())
794/// ```
795pub fn request(method: Method, url: &str) -> Result<Response, Error> {
796    Client::default().method(method).send(url)
797}
798
799/// Sends a request with the given method, URL, and headers using default builder settings.
800///
801/// # Errors
802/// Returns an error if the URL is invalid, a header name or value is malformed, the
803/// status code is unrecognized, or libcurl reports a failure.
804///
805/// # Examples
806/// ```no_run
807/// let resp = curl_rest::request_with_headers(
808///     curl_rest::Method::Get,
809///     "https://example.com",
810///     &[curl_rest::Header::AcceptEncoding("gzip".into())],
811/// )?;
812/// println!("Status: {}", resp.status);
813/// # Ok::<(), curl_rest::Error>(())
814/// ```
815pub fn request_with_headers(
816    method: Method,
817    url: &str,
818    headers: &[Header<'_>],
819) -> Result<Response, Error> {
820    Client::default()
821        .method(method)
822        .headers(headers.iter().cloned())
823        .send(url)
824}
825
826/// Sends a GET request using default builder settings.
827///
828/// # Errors
829/// Returns an error if the URL is invalid, the status code is unrecognized, or
830/// libcurl reports a failure.
831///
832/// # Examples
833/// ```no_run
834/// let resp = curl_rest::get("https://example.com")?;
835/// println!("Status: {}", resp.status);
836/// # Ok::<(), curl_rest::Error>(())
837/// ```
838pub fn get(url: &str) -> Result<Response, Error> {
839    Client::default().get().send(url)
840}
841
842/// Sends a POST request using default builder settings.
843///
844/// # Errors
845/// Returns an error if the URL is invalid, the status code is unrecognized, or
846/// libcurl reports a failure.
847///
848/// # Examples
849/// ```no_run
850/// let resp = curl_rest::post("https://example.com")?;
851/// println!("Status: {}", resp.status);
852/// # Ok::<(), curl_rest::Error>(())
853/// ```
854pub fn post(url: &str) -> Result<Response, Error> {
855    Client::default().post().send(url)
856}
857
858/// Sends a GET request with headers using default builder settings.
859///
860/// # Errors
861/// Returns an error if the URL is invalid, a header name or value is malformed, the
862/// status code is unrecognized, or libcurl reports a failure.
863///
864/// # Examples
865/// ```no_run
866/// let resp = curl_rest::get_with_headers(
867///     "https://example.com",
868///     &[curl_rest::Header::AcceptEncoding("gzip".into())],
869/// )?;
870/// println!("Status: {}", resp.status);
871/// # Ok::<(), curl_rest::Error>(())
872/// ```
873pub fn get_with_headers(url: &str, headers: &[Header<'_>]) -> Result<Response, Error> {
874    Client::default()
875        .get()
876        .headers(headers.iter().cloned())
877        .send(url)
878}
879
880/// Sends a POST request with headers using default builder settings.
881///
882/// # Errors
883/// Returns an error if the URL is invalid, a header name or value is malformed, the
884/// status code is unrecognized, or libcurl reports a failure.
885///
886/// # Examples
887/// ```no_run
888/// let resp = curl_rest::post_with_headers(
889///     "https://example.com",
890///     &[curl_rest::Header::AcceptEncoding("gzip".into())],
891/// )?;
892/// println!("Status: {}", resp.status);
893/// # Ok::<(), curl_rest::Error>(())
894/// ```
895pub fn post_with_headers(url: &str, headers: &[Header<'_>]) -> Result<Response, Error> {
896    Client::default()
897        .post()
898        .headers(headers.iter().cloned())
899        .send(url)
900}
901
902#[cfg(test)]
903mod tests {
904    use super::*;
905
906    #[test]
907    fn query_params_are_encoded_and_appended() {
908        let params = [
909            QueryParam::new("q", "rust curl"),
910            QueryParam::new("page", "1"),
911        ];
912        let url = add_query_params("https://example.com/search", &params);
913        assert_eq!(
914            url.as_ref(),
915            "https://example.com/search?q=rust%20curl&page=1"
916        );
917    }
918
919    #[test]
920    fn query_params_preserve_fragments() {
921        let params = [QueryParam::new("a", "b")];
922        let url = add_query_params("https://example.com/path#frag", &params);
923        assert_eq!(url.as_ref(), "https://example.com/path?a=b#frag");
924    }
925
926    #[test]
927    fn query_params_noop_is_borrowed() {
928        let url = add_query_params("https://example.com", &[]);
929        assert!(matches!(url, Cow::Borrowed(_)));
930    }
931
932    #[test]
933    fn header_rejects_newlines() {
934        let header = Header::UserAgent("bad\r\nvalue".into());
935        let err = header.to_line().expect_err("expected invalid header");
936        assert!(matches!(err, Error::InvalidHeaderValue(name) if name == "User-Agent"));
937    }
938
939    #[test]
940    fn custom_header_rejects_invalid_name() {
941        let header = Header::Custom("X Bad".into(), "ok".into());
942        let err = header.to_line().expect_err("expected invalid header name");
943        assert!(matches!(err, Error::InvalidHeaderName(name) if name == "X Bad"));
944    }
945
946    #[test]
947    fn custom_header_allows_standard_token_chars() {
948        let header = Header::Custom("X-Request-Id".into(), "abc123".into());
949        let line = header.to_line().expect("expected valid header");
950        assert_eq!(line, "X-Request-Id: abc123");
951    }
952
953    #[test]
954    fn body_content_type_defaults() {
955        let curl = Client::default().body_json(r#"{"ok":true}"#);
956        assert_eq!(curl.body_content_type(), Some("application/json"));
957
958        let curl = Client::default().body_text("hi");
959        assert_eq!(curl.body_content_type(), Some("text/plain; charset=utf-8"));
960    }
961
962    #[test]
963    fn content_type_header_overrides_body_default() {
964        let curl = Client::default()
965            .body_json(r#"{"ok":true}"#)
966            .header(Header::ContentType("application/custom+json".into()));
967        assert!(curl.has_content_type_header());
968        assert_eq!(curl.body_content_type(), Some("application/json"));
969    }
970
971    #[test]
972    fn with_user_agent_sets_default() {
973        let curl = Client::with_user_agent("my-agent/1.0");
974        assert_eq!(curl.default_user_agent.as_deref(), Some("my-agent/1.0"));
975    }
976
977    #[test]
978    fn user_agent_detection_handles_custom_header() {
979        let curl = Client::default().header(Header::Custom("User-Agent".into(), "custom".into()));
980        assert!(curl.has_user_agent_header());
981    }
982
983    #[test]
984    fn url_validation_rejects_invalid_urls() {
985        let err = validate_url("http://[::1").expect_err("expected invalid url");
986        assert!(matches!(err, Error::InvalidUrl(_)));
987    }
988
989    #[test]
990    fn query_params_append_to_existing_query() {
991        let params = [QueryParam::new("b", "2")];
992        let url = add_query_params("https://example.com/path?a=1", &params);
993        assert_eq!(url.as_ref(), "https://example.com/path?a=1&b=2");
994    }
995
996    #[test]
997    fn query_params_encode_unicode() {
998        let params = [QueryParam::new("q", "café")];
999        let url = add_query_params("https://example.com/search", &params);
1000        assert_eq!(url.as_ref(), "https://example.com/search?q=caf%C3%A9");
1001    }
1002
1003    #[test]
1004    fn header_name_and_value_match() {
1005        let header = Header::Accept("application/json".into());
1006        assert_eq!(header.name(), "Accept");
1007        assert_eq!(header.value(), "application/json");
1008    }
1009}
curl_rest/lib.rs

curl_rest/
lib.rs
