FeignHTTP

https://docs.rs/feignhttp/0.6.1/feignhttp/
Admin
FeignHTTP is a declarative HTTP client based on Rust macros, offering an easy-to-use, asynchronous...
Tokens:40,524
Snippets:363
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Handling File Metadata Operations with and_then

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

This example demonstrates chaining fallible file system operations using `and_then`. It shows how to safely get metadata and modified time, handling potential errors like `NotFound`.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Basic GET Request

Source: https://docs.rs/feignhttp

Demonstrates how to make a simple GET request using the `feignhttp::get` macro. The function returns a `Result` containing a String, which will hold the response body.

```APIDOC
## GET https://api.github.com

### Description
Sends a GET request to the specified URL and returns the response body as a String.

### Method
GET

### Endpoint
https://api.github.com

### Parameters
None

### Request Example
```rust
use feignhttp::get;

#[get("https://api.github.com")]
async fn github() -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = github().await?;
    println!("result: {}", r);
    Ok(())
}
```

### Response
#### Success Response (200)
- **String**: The response body from the server.
```

--------------------------------

### Product of Results Example

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Demonstrates how to calculate the product of elements in an iterator where each element is a Result. The operation short-circuits and returns the first Err encountered.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### Using the #[get] Attribute Macro

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/attr.get.html

This macro is used to define an HTTP GET request. Ensure it's applied correctly within your service definitions.

```rust
#[get]
```

--------------------------------

### Basic GET Request with FeignHTTP

Source: https://docs.rs/feignhttp

Demonstrates a simple GET request to an API endpoint using the `feignhttp::get` macro. Requires a runtime like Tokio. The function returns a `feignhttp::Result<String>`.

```rust
use feignhttp::get;

#[get("https://api.github.com")]
async fn github() -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = github().await?;
    println!("result: {}", r);

    Ok(())
}
```

--------------------------------

### Result Implementations

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Provides documentation and examples for various implementations of the Result type, including methods for copying, cloning, transposing, flattening, and checking the status of the result.

```APIDOC
## Implementations

### impl<T, E> Result<&T, E>

#### pub const fn copied(self) -> Result<T, E>
Maps a `Result<&T, E>` to a `Result<T, E>` by copying the contents of the `Ok` part.

##### Examples
```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

#### pub fn cloned(self) -> Result<T, E>
Maps a `Result<&T, E>` to a `Result<T, E>` by cloning the contents of the `Ok` part.

##### Examples
```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

### impl<T, E> Result<&mut T, E>

#### pub const fn copied(self) -> Result<T, E>
Maps a `Result<&mut T, E>` to a `Result<T, E>` by copying the contents of the `Ok` part.

##### Examples
```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

#### pub fn cloned(self) -> Result<T, E>
Maps a `Result<&mut T, E>` to a `Result<T, E>` by cloning the contents of the `Ok` part.

##### Examples
```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

### impl<T, E> Result<Option<T>, E>

#### pub const fn transpose(self) -> Option<Result<T, E>>
Transposes a `Result` of an `Option` into an `Option` of a `Result`.
`Ok(None)` will be mapped to `None`. `Ok(Some(_))` and `Err(_)` will be mapped to `Some(Ok(_))` and `Some(Err(_))`.

##### Examples
```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

### impl<T, E> Result<Result<T, E>, E>

#### pub const fn flatten(self) -> Result<T, E>
Converts from `Result<Result<T, E>, E>` to `Result<T, E>`

##### Examples
```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

Flattening only removes one level of nesting at a time:
```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

### impl<T, E> Result<T, E>

#### pub const fn is_ok(&self) -> bool
Returns `true` if the result is `Ok`.

##### Examples
```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

#### pub fn is_ok_and<F>(self, f: F) -> bool
where F: FnOnce(T) -> bool,
Returns `true` if the result is `Ok` and the value inside of it matches a predicate.

##### Examples
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

#### pub const fn is_err(&self) -> bool
Returns `true` if the result is `Err`.

##### Examples
```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```
```

--------------------------------

### Specify Multiple Headers with `headers` Attribute

Source: https://docs.rs/feignhttp

Use the `headers` key in the `get` attribute to specify one or more headers. The format must be `header-key1: header-value1; header-key2: header-value2;...`.

```rust
use feignhttp::get;

#[get("https://httpbin.org/headers", headers = "key1: value1; key2: value2")]
async fn headers() -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = headers().await?;
    println!("headers result: {}", r);

    Ok(())
}
```

--------------------------------

### GET Request with URL Constant and Path Parameters

Source: https://docs.rs/feignhttp

Demonstrates using a URL constant for the base URL and specifying path parameters. The URL constant can be the first argument or specified with `url =`.

```APIDOC
## GET https://api.github.com/repos/{owner}/{repo}/languages

### Description
Retrieves a list of languages used in a repository, using a URL constant and path parameters for owner and repository.

### Method
GET

### Endpoint
https://api.github.com/repos/{owner}/{repo}/languages

### Parameters
#### Path Parameters
- **owner** (String) - Required - The owner of the repository.
- **repo** (String) - Required - The name of the repository.

### Request Example
```rust
use feignhttp::get;

const GITHUB_URL: &str = "https://api.github.com";

#[get(url = GITHUB_URL, path = "/repos/{owner}/{repo}/languages")]
async fn languages(
    #[path] owner: &str,
    #[path] repo: &str,
) -> feignhttp::Result<String> {}
```

### Response
#### Success Response (200)
- **String**: The response body containing language information.
```

--------------------------------

### GET Request with Query Parameters

Source: https://docs.rs/feignhttp

Shows how to add query parameters to a GET request. Parameters without the `#[query]` attribute are automatically treated as query parameters.

```APIDOC
## GET https://api.github.com/repos/{owner}/{repo}/contributors?page={page}

### Description
Fetches contributors for a repository, including pagination via a query parameter.

### Method
GET

### Endpoint
https://api.github.com/repos/{owner}/{repo}/contributors

### Parameters
#### Path Parameters
- **owner** (String) - Required - The owner of the repository.
- **repo** (String) - Required - The name of the repository.

#### Query Parameters
- **page** (u32) - Required - The page number for contributors.

### Request Example
```rust
use feignhttp::get;

#[get("https://api.github.com/repos/{owner}/{repo}/contributors")]
async fn contributors(
    #[path] owner: &str,
    #[path] repo: &str,
    #[query] page: u32,
) -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = contributors("dxx", "feignhttp", 1).await?;
    println!("contributors result: {}", r);
    Ok(())
}
```

### Response
#### Success Response (200)
- **String**: The response body containing contributor information.
```

--------------------------------

### Set Request Method

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestBuilder.html

Sets the HTTP method for the request (e.g., GET, POST).

```rust
pub fn method(self, method: &'a str) -> Self
```

--------------------------------

### GET Request with Path Parameters

Source: https://docs.rs/feignhttp

Shows how to use path parameters in a URL. Path parameters are defined within curly braces in the URL and mapped to function arguments using `#[path]`.

```APIDOC
## GET https://api.github.com/repos/{owner}/{repo}

### Description
Fetches repository information using owner and repository name as path parameters.

### Method
GET

### Endpoint
https://api.github.com/repos/{owner}/{repo}

### Parameters
#### Path Parameters
- **owner** (String) - Required - The owner of the repository.
- **repo** (String) - Required - The name of the repository.

### Request Example
```rust
use feignhttp::get;

#[get("https://api.github.com/repos/{owner}/{repo}")]
async fn repository(
    #[path("owner")] user: &str,
    #[path] repo: String,
) -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = repository("dxx", "feignhttp".to_string()).await?;
    println!("repository result: {}", r);
    Ok(())
}
```

### Response
#### Success Response (200)
- **String**: The response body containing repository details.
```

--------------------------------

### Using Trait for Requests

Source: https://docs.rs/feignhttp

Define request methods within a trait for organized and reusable HTTP request definitions. This example shows how to define a trait with shared context and individual request methods.

```APIDOC
## Using Trait for Requests

Trait is a good way to manage requests. Define a Trait and then define a large number of request methods:

```rust
use feignhttp::{Context, FeignClientBuilder, feign};

#[derive(Context)]
struct GithubContext {
    // `url_path` and `param` are used to set the shared data.
    // The other two for share data are `header` and `query`.
    #[url_path("owner")]
    user: &'static str,
    #[url_path]
    repo: &'static str,
    #[param]
    accept: &'static str,
}

#[feign(
    url = "https://api.github.com/repos/{owner}/{repo}",
    headers = "Accept: {accept}"
)]
pub trait Github {
    // The method must have a self argument.
    #[get] async fn home(&self) -> feignhttp::Result<String>;

    #[get(path = "", headers = "Accept: application/json")]
    async fn repository(&self) -> feignhttp::Result<String>;

    #[get("/commits")]
    async fn commits(
        &self,
        #[header] accept: &str,
        #[query] page: u32,
        #[query] per_page: u32,
    ) -> feignhttp::Result<String>;

}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let context = GithubContext {
        user: "dxx",
        repo: "feignhttp",
        accept: "*/*",
    };

    let github = Github::builder().context(context).build()?;

    let r = github.home().await?;
    println!("github result: {}\n", r);

    Ok(())
}
```
```

--------------------------------

### Get references from Result

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Use `as_ref` to convert a `&Result<T, E>` into a `Result<&T, &E>`, allowing you to inspect the contained values without consuming the original Result.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Sum of Results Example

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Illustrates summing elements from an iterator of Results. If any element is an Err, the sum operation stops and returns that Err. This is useful for validating data during aggregation.

```rust
let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };
let v = vec![1, 2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Ok(3));
let v = vec![1, -2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Err("Negative element found"));
```

--------------------------------

### Deserialize JSON Response with `serde`

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/index.html

Enable the `reqwest-json` feature and use `serde::Deserialize` to automatically deserialize JSON responses into Rust structs. This example fetches a list of issues.

```rust
use feignhttp::get;
use serde::Deserialize;

// Deserialize: Specifies deserialization
#[derive(Debug, Deserialize)]
struct IssueItem {
    pub id: u32,
    pub number: u32,
    pub title: String,
    pub url: String,
    pub repository_url: String,
    pub state: String,
    pub body: Option<String>,
}

const GITHUB_URL: &str = "https://api.github.com";

#[get(url = GITHUB_URL, path = "/repos/{owner}/{repo}/issues")]
async fn issues(
    #[path] owner: &str,
    #[path] repo: &str,
    page: u32,
    per_page: u32,
) -> feignhttp::Result<Vec<IssueItem>> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = issues("octocat", "hello-world", 1, 2).await?;
    println!("issues: {:#?}", r);

    Ok(())
}
```

--------------------------------

### HttpClient::new

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.HttpClient.html

Creates a new HTTP client with default configuration.

```APIDOC
## HttpClient::new

### Description
Creates a new HTTP client with default configuration.

### Method
`pub fn new() -> Result<ClientWrapper>`

### Returns
A `Result` containing a `ClientWrapper` on success, or an error on failure.
```

--------------------------------

### HttpClient::with_config

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.HttpClient.html

Creates a new HTTP client with a custom configuration.

```APIDOC
## HttpClient::with_config

### Description
Creates a new HTTP client with a custom configuration.

### Method
`pub fn with_config(config: ClientConfig) -> Result<ClientWrapper>`

### Parameters
#### Request Body
- **config** (ClientConfig) - Required - The client configuration to use.

### Returns
A `Result` containing a `ClientWrapper` on success, or an error on failure.
```

--------------------------------

### Configuring Client Settings

Source: https://docs.rs/feignhttp

Configure global settings for trait-based clients, such as connection and request timeouts, using `ClientConfig`.

```APIDOC
## Configuration

You can use `ClientConfig` to configure timeout settings for trait-based clients:

```rust
use feignhttp::{ClientConfig, FeignClientBuilder, feign};

#[feign(url = "https://api.github.com")]
pub trait GitHub {
    #[get("/repos/{owner}/{repo}")]
    async fn repository(
        &self,
        #[path] owner: &str,
        #[path] repo: &str,
    ) -> feignhttp::Result<String>;
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfig {
        connect_timeout: Some(5000), // 5 seconds
        timeout: Some(10000),        // 10 seconds
        ..Default::default()
    };

    let github = GitHub::builder().config(config).build()?;

    let r = github.repository("dxx", "feignhttp").await?;
    println!("repository: {}\n", r);

    Ok(())
}
```
```

--------------------------------

### ClientConfig from_map Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Creates a ClientConfig instance from a HashMap of string slices to strings. This is useful for parsing configuration from external sources.

```rust
pub fn from_map(config_map: HashMap<&str, String>) -> Result<Self>
```

--------------------------------

### Result Termination Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Provides a `report` function to get the representation of the Result value as a status code, which is returned to the operating system.

```rust
impl<T, E> Termination for Result<T, E>
where T: Termination, E: Debug,
Source
```

--------------------------------

### Any Trait Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Provides runtime type information for ClientConfig.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### HttpRequest::send

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestWrapper.html

Sends the HTTP request asynchronously without a request body. This is typically used for methods like GET or DELETE.

```APIDOC
## HttpRequest::send

### Description
Sends the HTTP request asynchronously without a request body. This is typically used for methods like GET or DELETE.

### Method

```
fn send<'async_trait>( self, ) -> Pin<Box<dyn Future<Output = Result<Self::Response>> + Send + 'async_trait>>
where Self: 'async_trait
```

### Returns

A `Pin<Box<dyn Future<Output = Result<Self::Response>> + Send + 'async_trait>>>` which resolves to a `Result` containing a `ResponseWrapper` on success.
```

--------------------------------

### HttpRequest::send Method

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/trait.HttpRequest.html

Sends the HTTP request without a specific body. This is typically used for requests like GET or DELETE where the body is not required.

```rust
fn send<'async_trait>(
    self,
) -> Pin<Box<dyn Future<Output = Result<Self::Response>> + Send + 'async_trait>>
   where Self: 'async_trait,
```

--------------------------------

### ClientConfig::from_map

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Creates a ClientConfig from a HashMap of string slices and strings. This allows for flexible configuration of the HTTP client.

```APIDOC
## ClientConfig::from_map

### Description
Creates a `ClientConfig` from a `HashMap<&str, String>`.

### Method
`pub fn from_map(config_map: HashMap<&str, String>) -> Result<Self>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* `config_map` (HashMap<&str, String>) - A map containing configuration options.

### Request Example
```json
{
  "connect_timeout": "5000",
  "timeout": "10000",
  "read_timeout": "8000"
}
```

### Response
#### Success Response (Result<ClientConfig>)
Returns a `ClientConfig` instance if the provided map is valid.

#### Response Example
```json
{
  "connect_timeout": 5000,
  "timeout": 10000,
  "read_timeout": 8000
}
```
```

--------------------------------

### Attribute Macro delete

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/attr.delete.html

Use the #[delete] attribute macro to define an HTTP DELETE request. No specific setup or imports are required beyond the macro itself.

```rust
#[delete]
```

--------------------------------

### CloneToUninit Trait Implementation (Nightly)

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Nightly-only experimental API for cloning ClientConfig into uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Create RequestWrapper with Configuration

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestWrapper.html

Constructs a new RequestWrapper with a client wrapper, URL, method, and a specific RequestConfig. Returns a Result.

```rust
pub fn with_config( client_wrapper: ClientWrapper, url: &str, method: &str, config: RequestConfig, ) -> Result<RequestWrapper>
```

--------------------------------

### Expect Err value (panics on Ok)

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Use `expect_err()` to get the contained `Err` value. This method will panic if the `Result` is an `Ok`, providing a custom panic message.

```rust
let x: Result<u32, &str> = Ok(10);
x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`
```

--------------------------------

### Get mutable references from Result

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Use `as_mut` to convert a `&mut Result<T, E>` into a `Result<&mut T, &mut E>`, enabling in-place modification of the contained values.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### ClientConfig Default Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Provides a default configuration for ClientConfig, useful when no specific settings are required.

```rust
fn default() -> ClientConfig
```

--------------------------------

### Unwrap Ok value or return default

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Use `unwrap_or_default()` to get the contained `Ok` value or the default value for the type if it's an `Err`. This is useful for providing fallback values.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### Initialize RequestBuilder

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestBuilder.html

Creates a new instance of RequestBuilder.

```rust
pub fn new(client: ClientWrapper) -> Self
```

--------------------------------

### Customizing HTTP Client

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/index.html

Customizes the HTTP client using `ClientWrapper::with_client` for advanced configurations.

```APIDOC
## Customizing HTTP Client

You can customize the HTTP client by using `ClientWrapper::with_client`. This allows you to configure the client with custom settings before building the feign client:

```rust
use feignhttp::{ClientWrapper, Client, FeignClientBuilder, feign};

#[feign(url = "https://api.github.com")]
pub trait GitHub {
    #[get("/users/{user}")]
    async fn user(&self, #[path] user: &str) -> feignhttp::Result<String>;
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build a custom reqwest client with default headers
    let client = reqwest::Client::builder()
        .user_agent("Feign HTTP")
        .build()?;

    let client_wrapper = ClientWrapper::with_client(client)?;
    let github = GitHubBuilder::build_with_client(client_wrapper)?;

    let r = github.user("dxx").await?;
    println!("{}", r);

    Ok(())
}
```

See here for more examples.
```

--------------------------------

### Unwrap Err value (panics on Ok)

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Use `unwrap_err()` to get the contained `Err` value. This method will panic if the `Result` is an `Ok`. It is useful when you expect an error and want to extract its value.

```rust
let x: Result<u32, &str> = Ok(2);
x.unwrap_err(); // panics with `2`
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(x.unwrap_err(), "emergency failure");
```

--------------------------------

### From Trait Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Allows creating a ClientConfig from itself, returning the argument unchanged.

```rust
fn from(t: T) -> T
```

--------------------------------

### Using Trait for Requests

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/index.html

Demonstrates how to define and use traits to manage multiple HTTP requests with shared context and headers.

```APIDOC
## Using Trait for Requests

Trait is a good way to manage requests. Define a Trait and then define a large number of request methods:

```rust
use feignhttp::{Context, FeignClientBuilder, feign};

#[derive(Context)]
struct GithubContext {
    // `url_path` and `param` are used to set the shared data.
    // The other two for share data are `header` and `query`.
    #[url_path("owner")]
    user: &'static str,
    #[url_path]
    repo: &'static str,
    #[param]
    accept: &'static str,
}

#[feign(
    url = "https://api.github.com/repos/{owner}/{repo}",
    headers = "Accept: {accept}"
)]
pub trait Github {
    // The method must have a self argument.
    #[get]
    async fn home(&self) -> feignhttp::Result<String>;

    #[get(path = "", headers = "Accept: application/json")]
    async fn repository(&self) -> feignhttp::Result<String>;

    #[get("/commits")]
    async fn commits(
        &self,
        #[header] accept: &str,
        #[query] page: u32,
        #[query] per_page: u32,
    ) -> feignhttp::Result<String>;

}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let context = GithubContext {
        user: "dxx",
        repo: "feignhttp",
        accept: "*/*",
    };

    let github = Github::builder().context(context).build()?;

    let r = github.home().await?;
    println!("github result: {}\n", r);

    Ok(())
}
```

See here for a complete example.
```

--------------------------------

### ClientConfig Clone Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Allows creating a duplicate of an existing ClientConfig instance.

```rust
fn clone(&self) -> ClientConfig
```

--------------------------------

### Unwrap Ok value (panics on Err)

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Use `unwrap()` to get the contained `Ok` value. This method will panic if the `Result` is an `Err`. It is generally discouraged in favor of safer error handling methods.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`
```

--------------------------------

### Create RequestWrapper with ClientWrapper

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestWrapper.html

Constructs a new RequestWrapper with the provided client wrapper, URL, and HTTP method. Returns a Result.

```rust
pub fn new( client_wrapper: ClientWrapper, url: &str, method: &str, ) -> Result<RequestWrapper>
```

--------------------------------

### ClientConfig clone_from Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Performs copy-assignment from a source ClientConfig to the current one.

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

--------------------------------

### RequestBuilder::new

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestBuilder.html

Creates a new RequestBuilder instance.

```APIDOC
## RequestBuilder::new

### Description
Creates a new RequestBuilder instance.

### Method
```rust
pub fn new(client: ClientWrapper) -> Self
```
```

--------------------------------

### Policy 'Or' Combination

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestWrapper.html

Creates a new Policy that returns Action::Follow if either self or other policies return Action::Follow. Part of the PolicyExt trait.

```rust
fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>,
P: Policy<B, E>,
```

--------------------------------

### into_ok

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/type.Result.html

Returns the contained `Ok` value, but never panics. This is an experimental API.

```APIDOC
## pub const fn into_ok(self) -> T

### Description
Returns the contained `Ok` value, but never panics.
Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Examples
```

fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```
```

--------------------------------

### Policy 'And' Combination

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestWrapper.html

Creates a new Policy that returns Action::Follow only if both self and other policies return Action::Follow. Part of the PolicyExt trait.

```rust
fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>,
P: Policy<B, E>,
```

--------------------------------

### Sending Headers

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/index.html

Demonstrates how to specify request headers using the `header` attribute for individual headers or the `headers` attribute for multiple headers.

```APIDOC
## GET https://api.github.com/repos/dxx/feignhttp/commits

### Description
Fetches a list of commits for a given repository, allowing specification of headers and query parameters.

### Method
GET

### Endpoint
https://api.github.com/repos/dxx/feignhttp/commits

### Parameters
#### Query Parameters
- **page** (u32) - Required - The page number of the commits to retrieve.
- **per_page** (u32) - Required - The number of commits to return per page.

#### Request Headers
- **accept** (string) - Required - The Accept header value, e.g., "application/vnd.github.v3+json".

### Response
#### Success Response (200)
- **String** - A string representing the JSON response body containing commit information.

### Request Example
```rust
use feignhttp::get;

#[get("https://api.github.com/repos/dxx/feignhttp/commits")]
async fn commits(
    #[header] accept: &str,
    #[query] page: u32,
    #[query] per_page: u32,
) -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = commits("application/vnd.github.v3+json", 1, 5).await?;
    println!("commits result: {}", r);
    Ok(())
}
```

## GET https://httpbin.org/headers

### Description
An endpoint to test custom headers by returning them in the response.

### Method
GET

### Endpoint
https://httpbin.org/headers

### Parameters
#### Request Headers
- **key1** (string) - Required - Value for the first custom header.
- **key2** (string) - Required - Value for the second custom header.

### Response
#### Success Response (200)
- **String** - A string representing the JSON response body containing the request headers.

### Request Example
```rust
use feignhttp::get;

#[get("https://httpbin.org/headers", headers = "key1: value1; key2: value2")]
async fn headers() -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = headers().await?;
    println!("headers result: {}", r);
    Ok(())
}
```
```

--------------------------------

### Customizing HTTP Client with ClientWrapper

Source: https://docs.rs/feignhttp

Integrate a custom `reqwest::Client` with Feign HTTP using `ClientWrapper::with_client`. This enables pre-configuration of the HTTP client, such as setting default headers.

```rust
use feignhttp::{ClientWrapper, Client, FeignClientBuilder, feign};

#[feign(url = "https://api.github.com")]
pub trait GitHub {
    #[get("/users/{user}")]
    async fn user(&self, #[path] user: &str) -> feignhttp::Result<String>;
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build a custom reqwest client with default headers
    let client = reqwest::Client::builder()
        .user_agent("Feign HTTP")
        .build()?;

    let client_wrapper = ClientWrapper::with_client(client)?;
    let github = GitHubBuilder::build_with_client(client_wrapper)?;

    let r = github.user("dxx").await?;
    println!("{}", r);

    Ok(())
}
```

--------------------------------

### RequestWrapper::new

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestWrapper.html

Creates a new RequestWrapper with the provided client, URL, and HTTP method. This is a basic constructor for initiating a request.

```APIDOC
## RequestWrapper::new

### Description
Creates a new `RequestWrapper` with the provided client, URL, and HTTP method.

### Method

```
pub fn new( client_wrapper: ClientWrapper, url: &str, method: &str, ) -> Result<RequestWrapper>
```

### Parameters

*   **client_wrapper** (ClientWrapper) - The client wrapper to use for the request.
*   **url** (string) - The URL for the request.
*   **method** (string) - The HTTP method for the request (e.g., "GET", "POST").

### Returns

A `Result` containing a `RequestWrapper` on success, or an error if the request could not be created.
```

--------------------------------

### Client Wrapper Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/trait.Client.html

Implementation of the Client trait for ClientWrapper.

```APIDOC
### impl Client for ClientWrapper

#### type Inner = Client
```

--------------------------------

### RequestWrapper::with_config

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestWrapper.html

Creates a new RequestWrapper with a client, URL, HTTP method, and a specific RequestConfig. This allows for more detailed configuration of the request.

```APIDOC
## RequestWrapper::with_config

### Description
Creates a new `RequestWrapper` with a client, URL, HTTP method, and a specific `RequestConfig`. This allows for more detailed configuration of the request.

### Method

```
pub fn with_config( client_wrapper: ClientWrapper, url: &str, method: &str, config: RequestConfig, ) -> Result<RequestWrapper>
```

### Parameters

*   **client_wrapper** (ClientWrapper) - The client wrapper to use for the request.
*   **url** (string) - The URL for the request.
*   **method** (string) - The HTTP method for the request (e.g., "GET", "POST").
*   **config** (RequestConfig) - The configuration for the request.

### Returns

A `Result` containing a `RequestWrapper` on success, or an error if the request could not be created.
```

--------------------------------

### ClientConfig Struct Definition

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientConfig.html

Defines the structure for HTTP client configuration, including optional connection, general, and read timeouts.

```rust
pub struct ClientConfig {
    pub connect_timeout: Option<u64>,
    pub timeout: Option<u64>,
    pub read_timeout: Option<u64>,
}
```

--------------------------------

### Specify Request Header with `header` Attribute

Source: https://docs.rs/feignhttp

Use the `#[header]` attribute to specify a request header. A header `accept: application/vnd.github.v3+json` will be added.

```rust
use feignhttp::get;

#[get("https://api.github.com/repos/dxx/feignhttp/commits")]
async fn commits(
    #[header] accept: &str,
    #[query] page: u32,
    #[query] per_page: u32,
) -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = commits("application/vnd.github.v3+json", 1, 5).await?;
    println!("commits result: {}", r);

    Ok(())
}
```

--------------------------------

### FeignClientBuilder Methods

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/trait.FeignClientBuilder.html

This section details the methods available on the FeignClientBuilder trait for creating and configuring clients.

```APIDOC
## FeignClientBuilder

### Description
Provides methods to build and configure Feign clients.

### Methods

#### `new()`
Creates a new instance of the builder.

- **Returns**: `Self`

#### `config(config: ClientConfig)`
Configures the client with the provided `ClientConfig`.

- **Parameters**:
  - `config` (ClientConfig) - The client configuration.
- **Returns**: `Self`

#### `context<C>(context: C)`
Sets the Feign context for the client.

- **Parameters**:
  - `context` (C) - The Feign context, where `C` must implement `FeignContext` and be `'static`.
- **Returns**: `Self`

#### `build()`
Builds the Feign client.

- **Returns**: `Result<Self::Target>`
```

--------------------------------

### Client Wrapper Clone Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.ClientWrapper.html

Provides the ability to create a duplicate of a ClientWrapper instance. This is useful for scenarios where you need to maintain multiple independent client configurations.

```rust
fn clone(&self) -> ClientWrapper
```

--------------------------------

### PolicyExt Or Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestBuilder.html

Combines two policies, succeeding if either succeeds. Part of the PolicyExt trait.

```rust
fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>
```

--------------------------------

### Configuring Feign HTTP Client with ClientConfig

Source: https://docs.rs/feignhttp

Customize timeout settings for trait-based clients using `ClientConfig`. This allows setting connect and total timeouts in milliseconds.

```rust
use feignhttp::{ClientConfig, FeignClientBuilder, feign};

#[feign(url = "https://api.github.com")]
pub trait GitHub {
    #[get("/repos/{owner}/{repo}")]
    async fn repository(
        &self,
        #[path] owner: &str,
        #[path] repo: &str,
    ) -> feignhttp::Result<String>;
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfig {
        connect_timeout: Some(5000), // 5 seconds
        timeout: Some(10000),        // 10 seconds
        ..Default::default()
    };

    let github = GitHub::builder().config(config).build()?;

    let r = github.repository("dxx", "feignhttp").await?;
    println!("repository: {}\n", r);

    Ok(())
}
```

--------------------------------

### Set Request Configuration

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestBuilder.html

Applies custom configuration to the request.

```rust
pub fn config(self, config: RequestConfig) -> Self
```

--------------------------------

### RequestBuilder::build

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestBuilder.html

Builds and returns the RequestWrapper.

```APIDOC
## RequestBuilder::build

### Description
Builds and returns the RequestWrapper.

### Method
```rust
pub fn build(self) -> Result<RequestWrapper>
```
```

--------------------------------

### Making a POST Request with FeignHTTP

Source: https://docs.rs/feignhttp

Illustrates how to make a POST request using the `feignhttp::post` macro. The `#[body]` attribute marks a function parameter as the request body, which will be sent as plain text with `content-type: text/plain`.

```rust
use feignhttp::post;

#[post("https://httpbin.org/anything")]
async fn post_data(#[body] text: String) -> feignhttp::Result<String> {}
```

--------------------------------

### HttpRequest::headers Method

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/trait.HttpRequest.html

Sets the headers for the HTTP request. Use this to add custom headers like 'Authorization' or 'Content-Type'.

```rust
fn headers(self, headers: HashMap<&str, String>) -> Self;
```

--------------------------------

### Multipart File Upload

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/index.html

Illustrates how to upload files using multipart/form-data encoding with `part` for form fields and `file` for file uploads.

```APIDOC
## POST https://httpbin.org/post

### Description
Uploads a file along with form data using multipart/form-data encoding.

### Method
POST

### Endpoint
https://httpbin.org/post

### Parameters
#### Form Fields
- **name** (string) - Required - A form field named 'name'.

#### File Uploads
- **file** (PathBuf) - Required - The file to upload, specified with the form field name 'file'.

### Response
#### Success Response (200)
- **String** - A string representing the JSON response body containing the uploaded file and form data.

### Request Example
```rust
use feignhttp::post;
use std::path::PathBuf;

#[post("https://httpbin.org/post")]
async fn upload_file(
    #[file("file")] file: PathBuf,
    #[part("name")] name: &str,
) -> feignhttp::Result<String> {}
```

## POST https://httpbin.org/post

### Description
Uploads a file with custom content type and filename using multipart/form-data encoding.

### Method
POST

### Endpoint
https://httpbin.org/post

### Parameters
#### Form Fields
- **name** (string) - Required - A form field named 'name'.

#### File Uploads
- **file** (PathBuf) - Required - The file to upload, with specified content type and filename.
  - **content_type**: "image/png"
  - **filename**: "custom.png"

### Response
#### Success Response (200)
- **String** - A string representing the JSON response body containing the uploaded file and form data.

### Request Example
```rust
use feignhttp::post;
use std::path::PathBuf;

#[post("https://httpbin.org/post")]
async fn upload_file(
    #[file("file", content_type = "image/png", filename = "custom.png")] file: PathBuf,
    #[part("name")] name: &str,
) -> feignhttp::Result<String> {}
```
```

--------------------------------

### Set Request Query Parameters

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestBuilder.html

Adds query parameters to the URL.

```rust
pub fn query(self, query: Vec<(&'a str, String)>) -> Self
```

--------------------------------

### Using Query Parameters in FeignHTTP Requests

Source: https://docs.rs/feignhttp

Demonstrates how to add query parameters to a request using the `#[query]` attribute. Parameters without the `query` attribute are also added as query parameters by default.

```rust
use feignhttp::get;

#[get("https://api.github.com/repos/{owner}/{repo}/contributors")]
async fn contributors(
    #[path] owner: &str,
    #[path] repo: &str,
    #[query] page: u32,
) -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let r = contributors("dxx", "feignhttp", 1).await?;
    println!("contributors result: {}", r);

    Ok(())
}
```

--------------------------------

### Configuring FeignHTTP with isahc-client

Source: https://docs.rs/feignhttp

Shows how to configure FeignHTTP to use the `isahc` HTTP backend instead of the default `reqwest`. This is done by disabling default features and enabling the `isahc-client` feature in `Cargo.toml`.

```rust
feignhttp = { version = "0.6", default-features = false, features = ["isahc-client"] }
```

--------------------------------

### Replace Headers with Dynamic Parameters

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/index.html

Demonstrates replacing a header value with a dynamic parameter. The parameter must be annotated with `#[param]` and its value will be substituted into the header string.

```rust
use feignhttp::get;

#[get("https://httpbin.org/headers", headers = "token: {token}")]
async fn headers(#[param] token: &str) -> feignhttp::Result<String> {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // A request with a header `token: ZmVpZ25odHRw`.
    let res = headers("ZmVpZ25odHRw").await?;
    println!("headers: {}", res);

    Ok(())
}
```

--------------------------------

### PolicyExt And Implementation

Source: https://docs.rs/feignhttp/0.6.1/feignhttp/struct.RequestBuilder.html

Combines two policies, requiring both to succeed. Part of the PolicyExt trait.

```rust
fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>
```
Tokens:
Raw