Struct Request 

pub struct Request { /* private fields */ }

A typed HTTP request for GET or HEAD.

Implementations

impl Request

pub fn new<U: ToUrl>(method: Method, url: U) -> Result<Self, NanoGetError>

Creates a new request with the given method and URL.

pub fn get<U: ToUrl>(url: U) -> Result<Self, NanoGetError>

Creates a new GET request.

Examples found in repository

examples/custom-auth-handler/main.rs (line 50)

fn main() -> Result<(), Box<dyn Error>> {
    let Some(url) = env::var("NANO_GET_CUSTOM_AUTH_URL").ok() else {
        print_setup();
        return Ok(());
    };

    let client = Client::builder()
        .auth_handler(Arc::new(DemoTokenAuth))
        .build();
    let response = client.execute(Request::get(&url)?)?;

    println!("custom-auth-handler example");
    println!(
        "status: {} {}",
        response.status_code, response.reason_phrase
    );
    println!(
        "parsed WWW-Authenticate challenges: {}",
        response.www_authenticate_challenges()?.len()
    );

    Ok(())
}

examples/nano-get-bench.rs (line 53)

fn bench_get(iterations: usize) -> Duration {
    let response = b"HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhello".to_vec();
    let (base_url, handle) = spawn_persistent_server(iterations, response);

    let client = Client::builder()
        .connection_policy(ConnectionPolicy::Reuse)
        .build();
    let mut session = client.session();

    let start = Instant::now();
    for i in 0..iterations {
        let req = Request::get(format!("{}/g{}", base_url, i)).expect("request");
        let resp = session.execute(req).expect("execute");
        assert_eq!(resp.body, b"hello");
    }
    let elapsed = start.elapsed();
    handle.join().expect("join server");
    elapsed
}

fn bench_head(iterations: usize) -> Duration {
    let response = b"HTTP/1.1 200 OK\r\nContent-Length: 5\r\nX-Bench: 1\r\n\r\n".to_vec();
    let (base_url, handle) = spawn_persistent_server(iterations, response);

    let client = Client::builder()
        .connection_policy(ConnectionPolicy::Reuse)
        .build();
    let mut session = client.session();

    let start = Instant::now();
    for i in 0..iterations {
        let req = Request::head(format!("{}/h{}", base_url, i)).expect("request");
        let resp = session.execute(req).expect("execute");
        assert!(resp.body.is_empty());
    }
    let elapsed = start.elapsed();
    handle.join().expect("join server");
    elapsed
}

fn bench_pipeline(total_requests: usize, pipeline_depth: usize) -> Duration {
    let response = b"HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhello".to_vec();
    let (base_url, handle) = spawn_persistent_server(total_requests, response);

    let client = Client::builder()
        .connection_policy(ConnectionPolicy::Reuse)
        .build();
    let mut session = client.session();

    let start = Instant::now();
    let mut sent = 0usize;
    while sent < total_requests {
        let batch_size = (total_requests - sent).min(pipeline_depth);
        let mut batch = Vec::with_capacity(batch_size);
        for index in 0..batch_size {
            batch.push(Request::get(format!("{}/p{}", base_url, sent + index)).expect("request"));
        }
        let responses = session.execute_pipelined(&batch).expect("execute");
        assert_eq!(responses.len(), batch_size);
        for response in responses {
            assert_eq!(response.body, b"hello");
        }
        sent += batch_size;
    }
    let elapsed = start.elapsed();
    handle.join().expect("join server");
    elapsed
}

examples/session-reuse-and-pipelining/main.rs (line 20)

fn main() -> Result<(), Box<dyn Error>> {
    let client = Client::builder()
        .connection_policy(ConnectionPolicy::Reuse)
        .build();
    let mut session = client.session();

    let first = session.execute(Request::get("http://example.com/")?)?;
    let second = session.execute(Request::get("http://example.com/index.html")?)?;
    let pipelined = session.execute_pipelined(&[
        Request::get("http://example.com/")?,
        Request::get("http://example.com/index.html")?,
    ])?;

    println!("This example demonstrates the Session API shape for reuse and pipelining.");
    summarize("sequential #1", &first);
    summarize("sequential #2", &second);
    summarize("pipeline #1", &pipelined[0]);
    summarize("pipeline #2", &pipelined[1]);

    Ok(())
}

examples/memory-cache/main.rs (line 8)

fn main() -> Result<(), Box<dyn Error>> {
    let client = Client::builder().cache_mode(CacheMode::Memory).build();

    let first = Request::get("http://example.com")?;
    let mut second = Request::get("http://example.com")?;
    second.add_header("Cache-Control", "max-age=0, min-fresh=1")?;

    let first_response = client.execute(first)?;
    let second_response = client.execute(second)?;

    println!("memory cache example");
    println!(
        "first response: {} {}",
        first_response.status_code, first_response.reason_phrase
    );
    println!(
        "second response with request directives: {} {}",
        second_response.status_code, second_response.reason_phrase
    );
    println!("This example demonstrates cache configuration and cache-control request headers.");

    Ok(())
}

examples/request-builder/main.rs (line 16)

fn main() -> Result<(), Box<dyn Error>> {
    let url = "http://example.com";
    let mut request = Request::get(url)?.with_redirect_policy(RedirectPolicy::follow(5));

    request.add_header("Accept", "text/html,application/xhtml+xml")?;
    request.add_header("Cache-Control", "max-age=0")?;
    request.if_none_match("\"demo-etag\"")?;
    request.if_modified_since(UNIX_EPOCH + Duration::from_secs(784_111_777))?;
    request.range_bytes(Some(0), Some(255))?;

    // Protocol-managed headers such as Host and Connection are intentionally rejected by the
    // library. This example only uses safe end-to-end request headers.
    let response = request.execute()?;

    println!("manual request to {url}");
    println!(
        "status: {} {}",
        response.status_code, response.reason_phrase
    );
    println!("content-type: {:?}", response.header("content-type"));
    println!("body preview: {}", preview_text(response.body_text()?, 80));

    Ok(())
}

examples/basic-auth/main.rs (line 30)

fn main() -> Result<(), Box<dyn Error>> {
    let Some(url) = env::var("NANO_GET_BASIC_AUTH_URL").ok() else {
        print_setup();
        return Ok(());
    };

    let user = env_or_default("NANO_GET_BASIC_AUTH_USER", "demo-user");
    let pass = env_or_default("NANO_GET_BASIC_AUTH_PASS", "demo-pass");

    let challenge_driven = Client::builder()
        .basic_auth(user.clone(), pass.clone())
        .build()
        .execute(Request::get(&url)?)?;

    let preemptive = Client::builder()
        .preemptive_basic_auth(user.clone(), pass.clone())
        .build()
        .execute(Request::get(&url)?)?;

    let mut request = Request::get(&url)?;
    request.basic_auth(user, pass)?;
    let manual = request.execute()?;

    println!("basic-auth example");
    println!("challenge-driven status: {}", challenge_driven.status_code);
    println!("preemptive status: {}", preemptive.status_code);
    println!("request-level override status: {}", manual.status_code);

    Ok(())
}

Additional examples can be found in:

• examples/proxy-and-proxy-auth/main.rs

pub fn head<U: ToUrl>(url: U) -> Result<Self, NanoGetError>

Creates a new HEAD request.

Examples found in repository

examples/nano-get-bench.rs (line 73)

fn bench_head(iterations: usize) -> Duration {
    let response = b"HTTP/1.1 200 OK\r\nContent-Length: 5\r\nX-Bench: 1\r\n\r\n".to_vec();
    let (base_url, handle) = spawn_persistent_server(iterations, response);

    let client = Client::builder()
        .connection_policy(ConnectionPolicy::Reuse)
        .build();
    let mut session = client.session();

    let start = Instant::now();
    for i in 0..iterations {
        let req = Request::head(format!("{}/h{}", base_url, i)).expect("request");
        let resp = session.execute(req).expect("execute");
        assert!(resp.body.is_empty());
    }
    let elapsed = start.elapsed();
    handle.join().expect("join server");
    elapsed
}

pub fn method(&self) -> Method

Returns the request method.

pub fn url(&self) -> &Url

Returns the parsed request URL.

pub fn headers(&self) -> &[Header]

Returns all request headers in insertion order.

pub fn header(&self, name: &str) -> Option<&str>

Returns the first header value matching name (case-insensitive).

pub fn headers_named<'a>( &'a self, name: &'a str, ) -> impl Iterator<Item = &'a Header> + 'a

Iterates over all headers matching name (case-insensitive), preserving insertion order.

pub fn redirect_policy(&self) -> RedirectPolicy

Returns this request’s redirect policy.

pub fn with_redirect_policy(self, policy: RedirectPolicy) -> Self

Sets redirect policy on this request using builder style.

Examples found in repository

examples/request-builder/main.rs (line 16)

fn main() -> Result<(), Box<dyn Error>> {
    let url = "http://example.com";
    let mut request = Request::get(url)?.with_redirect_policy(RedirectPolicy::follow(5));

    request.add_header("Accept", "text/html,application/xhtml+xml")?;
    request.add_header("Cache-Control", "max-age=0")?;
    request.if_none_match("\"demo-etag\"")?;
    request.if_modified_since(UNIX_EPOCH + Duration::from_secs(784_111_777))?;
    request.range_bytes(Some(0), Some(255))?;

    // Protocol-managed headers such as Host and Connection are intentionally rejected by the
    // library. This example only uses safe end-to-end request headers.
    let response = request.execute()?;

    println!("manual request to {url}");
    println!(
        "status: {} {}",
        response.status_code, response.reason_phrase
    );
    println!("content-type: {:?}", response.header("content-type"));
    println!("body preview: {}", preview_text(response.body_text()?, 80));

    Ok(())
}

pub fn set_redirect_policy(&mut self, policy: RedirectPolicy) -> &mut Self

Sets redirect policy on this request in-place.

pub fn add_header( &mut self, name: impl Into<String>, value: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Appends a header without replacing existing headers of the same name.

Protocol-managed and hop-by-hop header names are rejected.

Examples found in repository

examples/memory-cache/main.rs (line 10)

fn main() -> Result<(), Box<dyn Error>> {
    let client = Client::builder().cache_mode(CacheMode::Memory).build();

    let first = Request::get("http://example.com")?;
    let mut second = Request::get("http://example.com")?;
    second.add_header("Cache-Control", "max-age=0, min-fresh=1")?;

    let first_response = client.execute(first)?;
    let second_response = client.execute(second)?;

    println!("memory cache example");
    println!(
        "first response: {} {}",
        first_response.status_code, first_response.reason_phrase
    );
    println!(
        "second response with request directives: {} {}",
        second_response.status_code, second_response.reason_phrase
    );
    println!("This example demonstrates cache configuration and cache-control request headers.");

    Ok(())
}

examples/request-builder/main.rs (line 18)

fn main() -> Result<(), Box<dyn Error>> {
    let url = "http://example.com";
    let mut request = Request::get(url)?.with_redirect_policy(RedirectPolicy::follow(5));

    request.add_header("Accept", "text/html,application/xhtml+xml")?;
    request.add_header("Cache-Control", "max-age=0")?;
    request.if_none_match("\"demo-etag\"")?;
    request.if_modified_since(UNIX_EPOCH + Duration::from_secs(784_111_777))?;
    request.range_bytes(Some(0), Some(255))?;

    // Protocol-managed headers such as Host and Connection are intentionally rejected by the
    // library. This example only uses safe end-to-end request headers.
    let response = request.execute()?;

    println!("manual request to {url}");
    println!(
        "status: {} {}",
        response.status_code, response.reason_phrase
    );
    println!("content-type: {:?}", response.header("content-type"));
    println!("body preview: {}", preview_text(response.body_text()?, 80));

    Ok(())
}

pub fn set_header( &mut self, name: impl Into<String>, value: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Sets a header value by removing existing headers with the same name first.

Protocol-managed and hop-by-hop header names are rejected.

pub fn remove_headers_named(&mut self, name: &str) -> &mut Self

Removes all headers with the provided name.

pub fn if_none_match( &mut self, etag: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Sets If-None-Match.

Examples found in repository

examples/request-builder/main.rs (line 20)

fn main() -> Result<(), Box<dyn Error>> {
    let url = "http://example.com";
    let mut request = Request::get(url)?.with_redirect_policy(RedirectPolicy::follow(5));

    request.add_header("Accept", "text/html,application/xhtml+xml")?;
    request.add_header("Cache-Control", "max-age=0")?;
    request.if_none_match("\"demo-etag\"")?;
    request.if_modified_since(UNIX_EPOCH + Duration::from_secs(784_111_777))?;
    request.range_bytes(Some(0), Some(255))?;

    // Protocol-managed headers such as Host and Connection are intentionally rejected by the
    // library. This example only uses safe end-to-end request headers.
    let response = request.execute()?;

    println!("manual request to {url}");
    println!(
        "status: {} {}",
        response.status_code, response.reason_phrase
    );
    println!("content-type: {:?}", response.header("content-type"));
    println!("body preview: {}", preview_text(response.body_text()?, 80));

    Ok(())
}

pub fn if_match( &mut self, etag: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Sets If-Match.

pub fn if_modified_since( &mut self, timestamp: SystemTime, ) -> Result<&mut Self, NanoGetError>

Sets If-Modified-Since using IMF-fixdate formatting.

Examples found in repository

examples/request-builder/main.rs (line 21)

fn main() -> Result<(), Box<dyn Error>> {
    let url = "http://example.com";
    let mut request = Request::get(url)?.with_redirect_policy(RedirectPolicy::follow(5));

    request.add_header("Accept", "text/html,application/xhtml+xml")?;
    request.add_header("Cache-Control", "max-age=0")?;
    request.if_none_match("\"demo-etag\"")?;
    request.if_modified_since(UNIX_EPOCH + Duration::from_secs(784_111_777))?;
    request.range_bytes(Some(0), Some(255))?;

    // Protocol-managed headers such as Host and Connection are intentionally rejected by the
    // library. This example only uses safe end-to-end request headers.
    let response = request.execute()?;

    println!("manual request to {url}");
    println!(
        "status: {} {}",
        response.status_code, response.reason_phrase
    );
    println!("content-type: {:?}", response.header("content-type"));
    println!("body preview: {}", preview_text(response.body_text()?, 80));

    Ok(())
}

pub fn if_unmodified_since( &mut self, timestamp: SystemTime, ) -> Result<&mut Self, NanoGetError>

Sets If-Unmodified-Since using IMF-fixdate formatting.

pub fn if_range( &mut self, value: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Sets If-Range.

pub fn authorization( &mut self, value: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Sets an explicit Authorization header for this request.

Manual request-level credentials take precedence over automatic client-level auth helpers.

pub fn proxy_authorization( &mut self, value: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Sets an explicit Proxy-Authorization header for this request.

Manual request-level credentials take precedence over automatic client-level proxy auth helpers.

pub fn basic_auth( &mut self, username: impl Into<String>, password: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Encodes username:password as HTTP Basic credentials and stores them in Authorization.

Examples found in repository

examples/basic-auth/main.rs (line 38)

fn main() -> Result<(), Box<dyn Error>> {
    let Some(url) = env::var("NANO_GET_BASIC_AUTH_URL").ok() else {
        print_setup();
        return Ok(());
    };

    let user = env_or_default("NANO_GET_BASIC_AUTH_USER", "demo-user");
    let pass = env_or_default("NANO_GET_BASIC_AUTH_PASS", "demo-pass");

    let challenge_driven = Client::builder()
        .basic_auth(user.clone(), pass.clone())
        .build()
        .execute(Request::get(&url)?)?;

    let preemptive = Client::builder()
        .preemptive_basic_auth(user.clone(), pass.clone())
        .build()
        .execute(Request::get(&url)?)?;

    let mut request = Request::get(&url)?;
    request.basic_auth(user, pass)?;
    let manual = request.execute()?;

    println!("basic-auth example");
    println!("challenge-driven status: {}", challenge_driven.status_code);
    println!("preemptive status: {}", preemptive.status_code);
    println!("request-level override status: {}", manual.status_code);

    Ok(())
}

pub fn proxy_basic_auth( &mut self, username: impl Into<String>, password: impl Into<String>, ) -> Result<&mut Self, NanoGetError>

Encodes username:password as HTTP Basic credentials and stores them in Proxy-Authorization.

Examples found in repository

examples/proxy-and-proxy-auth/main.rs (line 45)

fn main() -> Result<(), Box<dyn Error>> {
    let Some(proxy_url) = env::var("NANO_GET_PROXY_URL").ok() else {
        print_setup();
        return Ok(());
    };

    let target_url = env_or_default("NANO_GET_PROXY_TARGET_URL", "http://example.com");
    let proxy_user = env_or_default("NANO_GET_PROXY_AUTH_USER", "proxy-user");
    let proxy_pass = env_or_default("NANO_GET_PROXY_AUTH_PASS", "proxy-pass");

    let mut proxy = ProxyConfig::new(proxy_url)?;
    proxy.add_header("X-Example-Proxy", "nano-get-demo")?;

    let challenge_driven = Client::builder()
        .proxy(proxy.clone())
        .basic_proxy_auth(proxy_user.clone(), proxy_pass.clone())
        .build()
        .execute(Request::get(&target_url)?)?;

    let preemptive = Client::builder()
        .proxy(proxy.clone())
        .preemptive_basic_proxy_auth(proxy_user.clone(), proxy_pass.clone())
        .build()
        .execute(Request::get(&target_url)?)?;

    let mut manual = Request::get(&target_url)?;
    manual.proxy_basic_auth(proxy_user, proxy_pass)?;
    let manual_response = Client::builder().proxy(proxy).build().execute(manual)?;

    println!("proxy-and-proxy-auth example");
    println!("challenge-driven status: {}", challenge_driven.status_code);
    println!("preemptive status: {}", preemptive.status_code);
    println!(
        "request-level override status: {}",
        manual_response.status_code
    );

    Ok(())
}

pub fn range_bytes( &mut self, start: Option<u64>, end: Option<u64>, ) -> Result<&mut Self, NanoGetError>

Sets a Range header for byte-range requests.

Valid forms:

• Some(start), Some(end) => bytes=start-end
• Some(start), None => bytes=start-
• None, Some(end) => bytes=-end

Examples found in repository

examples/request-builder/main.rs (line 22)

fn main() -> Result<(), Box<dyn Error>> {
    let url = "http://example.com";
    let mut request = Request::get(url)?.with_redirect_policy(RedirectPolicy::follow(5));

    request.add_header("Accept", "text/html,application/xhtml+xml")?;
    request.add_header("Cache-Control", "max-age=0")?;
    request.if_none_match("\"demo-etag\"")?;
    request.if_modified_since(UNIX_EPOCH + Duration::from_secs(784_111_777))?;
    request.range_bytes(Some(0), Some(255))?;

    // Protocol-managed headers such as Host and Connection are intentionally rejected by the
    // library. This example only uses safe end-to-end request headers.
    let response = request.execute()?;

    println!("manual request to {url}");
    println!(
        "status: {} {}",
        response.status_code, response.reason_phrase
    );
    println!("content-type: {:?}", response.header("content-type"));
    println!("body preview: {}", preview_text(response.body_text()?, 80));

    Ok(())
}

pub fn execute(&self) -> Result<Response, NanoGetError>

Executes this request using Client::default.

Use crate::Client directly when you need explicit client configuration.

Examples found in repository

examples/request-builder/main.rs (line 26)

fn main() -> Result<(), Box<dyn Error>> {
    let url = "http://example.com";
    let mut request = Request::get(url)?.with_redirect_policy(RedirectPolicy::follow(5));

    request.add_header("Accept", "text/html,application/xhtml+xml")?;
    request.add_header("Cache-Control", "max-age=0")?;
    request.if_none_match("\"demo-etag\"")?;
    request.if_modified_since(UNIX_EPOCH + Duration::from_secs(784_111_777))?;
    request.range_bytes(Some(0), Some(255))?;

    // Protocol-managed headers such as Host and Connection are intentionally rejected by the
    // library. This example only uses safe end-to-end request headers.
    let response = request.execute()?;

    println!("manual request to {url}");
    println!(
        "status: {} {}",
        response.status_code, response.reason_phrase
    );
    println!("content-type: {:?}", response.header("content-type"));
    println!("body preview: {}", preview_text(response.body_text()?, 80));

    Ok(())
}

examples/basic-auth/main.rs (line 39)

fn main() -> Result<(), Box<dyn Error>> {
    let Some(url) = env::var("NANO_GET_BASIC_AUTH_URL").ok() else {
        print_setup();
        return Ok(());
    };

    let user = env_or_default("NANO_GET_BASIC_AUTH_USER", "demo-user");
    let pass = env_or_default("NANO_GET_BASIC_AUTH_PASS", "demo-pass");

    let challenge_driven = Client::builder()
        .basic_auth(user.clone(), pass.clone())
        .build()
        .execute(Request::get(&url)?)?;

    let preemptive = Client::builder()
        .preemptive_basic_auth(user.clone(), pass.clone())
        .build()
        .execute(Request::get(&url)?)?;

    let mut request = Request::get(&url)?;
    request.basic_auth(user, pass)?;
    let manual = request.execute()?;

    println!("basic-auth example");
    println!("challenge-driven status: {}", challenge_driven.status_code);
    println!("preemptive status: {}", preemptive.status_code);
    println!("request-level override status: {}", manual.status_code);

    Ok(())
}

Trait Implementations

impl Clone for Request

fn clone(&self) -> Request

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Request

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.