An enhanced http client with retry and hystrix capabilities

# Heimdall

<p align="center"><img src="doc/heimdall-logo.png" width="360"></p>
<p align="center">
  <a href="https://github.com/gojek/heimdall/actions"><img src="https://github.com/gojek/heimdall/actions/workflows/ci.yml/badge.svg" alt="Build Status"></img></a>
  <a href="https://goreportcard.com/report/github.com/gojek/heimdall"><img src="https://goreportcard.com/badge/github.com/gojek/heimdall"></img></a>
  <a href="https://golangci.com"><img src="https://golangci.com/badges/github.com/gojek/heimdall.svg"></img></a>
  <a href="https://coveralls.io/github/gojek/heimdall?branch=master"><img src="https://coveralls.io/repos/github/gojek/heimdall/badge.svg?branch=master"></img></a>
</p>

* [Description](#description)
* [Installation](#installation)
* [Usage](#usage)
  + [Making a simple `GET` request](#making-a-simple-get-request)
  + [Creating a hystrix-like circuit breaker](#creating-a-hystrix-like-circuit-breaker)
  + [Creating a hystrix-like circuit breaker with fallbacks](#creating-a-hystrix-like-circuit-breaker-with-fallbacks)
  + [Creating an HTTP client with a retry mechanism](#creating-an-http-client-with-a-retry-mechanism)
  + [Custom retry mechanisms](#custom-retry-mechanisms)
  + [Custom HTTP clients](#custom-http-clients)
* [Plugins](#plugins)
* [Documentation](#documentation)
* [FAQ](#faq)
* [License](#license)

## Description

Heimdall is an HTTP client that helps your application make a large number of requests, at scale. With Heimdall, you can:
- Use a [hystrix-like](https://github.com/afex/hystrix-go) circuit breaker to control failing requests
- Add synchronous in-memory retries to each request, with the option of setting your own retrier strategy
- Create clients with different timeouts for every request

All HTTP methods are exposed as a fluent interface.

## Installation
```
go get -u github.com/gojek/heimdall/v7
```

## Usage

### Importing the package

This package can be used by adding the following import statement to your `.go` files.

```go
import "github.com/gojek/heimdall/v7/httpclient" 
```

### Making a simple `GET` request
The below example will print the contents of the google home page:

```go
// Create a new HTTP client with a default timeout
timeout := 1000 * time.Millisecond
client := httpclient.NewClient(httpclient.WithHTTPTimeout(timeout))

// Use the clients GET method to create and execute the request
res, err := client.Get("http://google.com", nil)
if err != nil{
	panic(err)
}

// Heimdall returns the standard *http.Response object
body, err := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
```

You can also use the `*http.Request` object with the `http.Do` interface :

```go
timeout := 1000 * time.Millisecond
client := httpclient.NewClient(httpclient.WithHTTPTimeout(timeout))

// Create an http.Request instance
req, _ := http.NewRequest(http.MethodGet, "http://google.com", nil)
// Call the `Do` method, which has a similar interface to the `http.Do` method
res, err := client.Do(req)
if err != nil {
	panic(err)
}

body, err := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
```

### Creating a hystrix-like circuit breaker

To import hystrix package of heimdall.

```go
import "github.com/gojek/heimdall/v7/hystrix"
```

You can use the `hystrix.NewClient` function to create a client wrapped in a hystrix-like circuit breaker:

```go
// Create a new hystrix-wrapped HTTP client with the command name, along with other required options
client := hystrix.NewClient(
	hystrix.WithHTTPTimeout(10 * time.Millisecond),
	hystrix.WithCommandName("google_get_request"),
	hystrix.WithHystrixTimeout(1000 * time.Millisecond),
	hystrix.WithMaxConcurrentRequests(30),
	hystrix.WithErrorPercentThreshold(20),
	hystrix.WithStatsDCollector("localhost:8125", "myapp.hystrix"),
)

// The rest is the same as the previous example
```

In the above example, there are two timeout values used: one for the hystrix configuration, and one for the HTTP client configuration. The former determines the time at which hystrix should register an error, while the latter determines when the client itself should return a timeout error. Unless you have any special requirements, both of these would have the same values.

You can choose to export hystrix metrics to a statsD collector with the `hystrix.WithStatsDCollector(<statsd addr>, <metrics-prefix>)` option when initializing the client as shown above.

### Creating a hystrix-like circuit breaker with fallbacks

You can use the `hystrix.NewClient` function to create a client wrapped in a hystrix-like circuit breaker by passing in your own custom fallbacks:

The fallback function will trigger when your code returns an error, or whenever it is unable to complete based on a variety of [health checks](https://github.com/Netflix/Hystrix/wiki/How-it-Works).

**How your fallback function should look like**
you should pass in a function whose signature looks like following

```go
func(err error) error {
    // your logic for handling the error/outage condition
    return err
}
```


**Example**

```go
// Create a new fallback function
fallbackFn := func(err error) error {
    _, err := http.Post("post_to_channel_two")
    return err
}

timeout := 10 * time.Millisecond

// Create a new hystrix-wrapped HTTP client with the fallbackFunc as fall-back function
client := hystrix.NewClient(
	hystrix.WithHTTPTimeout(timeout),
	hystrix.WithCommandName("MyCommand"),
	hystrix.WithHystrixTimeout(1100 * time.Millisecond),
	hystrix.WithMaxConcurrentRequests(100),
	hystrix.WithErrorPercentThreshold(20),
	hystrix.WithSleepWindow(10),
	hystrix.WithRequestVolumeThreshold(10),
	hystrix.WithFallbackFunc(fallbackFn),
})

// The rest is the same as the previous example
```

In the above example, the `fallbackFunc` is a function which posts to channel two in case posting to channel one fails.

### Creating an HTTP client with a retry mechanism

```go
// First set a backoff mechanism. Constant backoff increases the backoff at a constant rate
backoffInterval := 2 * time.Millisecond
// Define a maximum jitter interval. It must be more than 1*time.Millisecond
maximumJitterInterval := 5 * time.Millisecond

backoff := heimdall.NewConstantBackoff(backoffInterval, maximumJitterInterval)

// Create a new retry mechanism with the backoff
retrier := heimdall.NewRetrier(backoff)

timeout := 1000 * time.Millisecond
// Create a new client, sets the retry mechanism, and the number of times you would like to retry
client := httpclient.NewClient(
	httpclient.WithHTTPTimeout(timeout),
	httpclient.WithRetrier(retrier),
	httpclient.WithRetryCount(4),
)

// The rest is the same as the first example
```
Or create client with exponential backoff

```go
// First set a backoff mechanism. Exponential Backoff increases the backoff at a exponential rate

initalTimeout := 2*time.Millisecond            // Inital timeout
maxTimeout := 9*time.Millisecond               // Max time out
exponentFactor := 2                            // Multiplier
maximumJitterInterval := 2*time.Millisecond    // Max jitter interval. It must be more than 1*time.Millisecond

backoff := heimdall.NewExponentialBackoff(initalTimeout, maxTimeout, exponentFactor, maximumJitterInterval)

// Create a new retry mechanism with the backoff
retrier := heimdall.NewRetrier(backoff)

timeout := 1000 * time.Millisecond
// Create a new client, sets the retry mechanism, and the number of times you would like to retry
client := httpclient.NewClient(
	httpclient.WithHTTPTimeout(timeout),
	httpclient.WithRetrier(retrier),
	httpclient.WithRetryCount(4),
)

// The rest is the same as the first example
```

This will create an HTTP client which will retry every `500` milliseconds incase the request fails. The library also comes with an [Exponential Backoff](https://pkg.go.dev/github.com/gojek/heimdall#NewExponentialBackoff)

### Custom retry mechanisms

Heimdall supports custom retry strategies. To do this, you will have to implement the `Backoff` interface:

```go
type Backoff interface {
	Next(retry int) time.Duration
}
```

Let's see an example of creating a client with a linearly increasing backoff time:

First, create the backoff mechanism:

```go
type linearBackoff struct {
	backoffInterval int
}

func (lb *linearBackoff) Next(retry int) time.Duration{
	if retry <= 0 {
		return 0 * time.Millisecond
	}
	return time.Duration(retry * lb.backoffInterval) * time.Millisecond
}
```

This will create a backoff mechanism, where the retry time will increase linearly for each retry attempt. We can use this to create the client, just like the last example:

```go
backoff := &linearBackoff{100}
retrier := heimdall.NewRetrier(backoff)

timeout := 1000 * time.Millisecond
// Create a new client, sets the retry mechanism, and the number of times you would like to retry
client := httpclient.NewClient(
	httpclient.WithHTTPTimeout(timeout),
	httpclient.WithRetrier(retrier),
	httpclient.WithRetryCount(4),
)

// The rest is the same as the first example
```

Heimdall also allows you to simply pass a function that returns the retry timeout. This can be used to create the client, like:
```go
linearRetrier := NewRetrierFunc(func(retry int) time.Duration {
	if retry <= 0 {
		return 0 * time.Millisecond
	}
	return time.Duration(retry) * time.Millisecond
})

timeout := 1000 * time.Millisecond
client := httpclient.NewClient(
	httpclient.WithHTTPTimeout(timeout),
	httpclient.WithRetrier(linearRetrier),
	httpclient.WithRetryCount(4),
)
```

### Custom HTTP clients

Heimdall supports custom HTTP clients. This is useful if you are using a client imported from another library and/or wish to implement custom logging, cookies, headers etc for each request that you make with your client.

Under the hood, the `httpClient` struct now accepts `Doer`, which is the standard interface implemented by HTTP clients (including the standard library's `net/*http.Client`)

Let's say we wish to add authorization headers to all our requests.

We can define our client `myHTTPClient`

```go
type myHTTPClient struct {
	client http.Client
}

func (c *myHTTPClient) Do(request *http.Request) (*http.Response, error) {
	request.SetBasicAuth("username", "passwd")
	return c.client.Do(request)
}
```

And set this with `httpclient.NewClient(httpclient.WithHTTPClient(&myHTTPClient{client: http.DefaultClient}))`

Now, each sent request will have the `Authorization` header to use HTTP basic authentication with the provided username and password.

This can be done for the hystrix client as well

```go
client := httpclient.NewClient(
	httpclient.WithHTTPClient(&myHTTPClient{
		client: http.Client{Timeout: 25 * time.Millisecond},
	}),
)

// The rest is the same as the first example
```

## Plugins

To add a plugin to an existing client, use the `AddPlugin` method of the client. 

An example, with the [request logger plugin](/plugins/request_logger.go):

```go
// import "github.com/gojek/heimdall/v7/plugins"

client := heimdall.NewHTTPClient(timeout)
requestLogger := plugins.NewRequestLogger(nil, nil)
client.AddPlugin(requestLogger)
// use the client as before

req, _ := http.NewRequest(http.MethodGet, "http://google.com", nil)
res, err := client.Do(req)
if err != nil {
	panic(err)
}
// This will log:
//23/Jun/2018 12:48:04 GET http://google.com 200 [412ms]
// to STDOUT
```

A plugin is an interface whose methods get called during key events in a requests lifecycle:

- `OnRequestStart` is called just before the request is made
- `OnRequestEnd` is called once the request has successfully executed
- `OnError` is called is the request failed

Each method is called with the request object as an argument, with `OnRequestEnd`, and `OnError` additionally being called with the response and error instances respectively.
For a simple example on how to write plugins, look at the [request logger plugin](/plugins/request_logger.go).

## Documentation

Further documentation can be found on [pkg.go.dev](https://pkg.go.dev/github.com/gojek/heimdall/v7)

## FAQ

**Can I replace the standard Go HTTP client with Heimdall?**

Yes, you can. Heimdall implements the standard [HTTP Do](https://golang.org/pkg/net/http/#Client.Do) method, along with [useful wrapper methods](https://golang.org/pkg/net/http/#Client.Do) that provide all the functionality that a regular Go HTTP client provides.

---

**When should I use Heimdall?**

If you are making a large number of HTTP requests, or if you make requests among multiple distributed nodes, and wish to make your systems more fault tolerant, then Heimdall was made for you.

Heimdall makes use of [multiple mechanisms](https://medium.com/@sohamkamani/how-to-handle-microservice-communication-at-scale-a6fb0ee0ed7) to make HTTP requests more fault tolerant:
1. Retries - If a request fails, Heimdall retries behind the scenes, and returns the result if one of the retries are successful.
2. Circuit breaking - If Heimdall detects that too many of your requests are failing, or that the number of requests sent are above a configured threshold, then it "opens the circuit" for a short period of time, which prevents any more requests from being made. _This gives your downstream systems time to recover._

---

**So does this mean that I shouldn't use Heimdall for small scale applications?**

Although Heimdall was made keeping large scale systems in mind, it's interface is simple enough to be used for any type of systems. In fact, we use it for our pet projects as well. Even if you don't require retries or circuit breaking features, the [simpler HTTP client](https://github.com/gojek/heimdall#making-a-simple-get-request) provides sensible defaults with a simpler interface, and can be upgraded easily should the need arise.

---

**Can I contribute to make Heimdall better?**

[Please do!](https://github.com/gojek/heimdall/blob/master/CONTRIBUTING.md) We are looking for any kind of contribution to improve Heimdalls core funtionality and documentation. When in doubt, make a PR!

## License

```
Copyright 2018-2020, GO-JEK Tech (http://gojek.tech)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```


heimdall

Simple Go HTTP client with Black Magic (Less code and More efficiency)

# req

<p align="center">
    <p align="center"><img src="https://req.cool/images/req.png"></p>
    <p align="center"><strong>Simple Go HTTP client with Black Magic</strong></p>
    <p align="center">
        <a href="https://github.com/imroc/req/actions/workflows/ci.yml?query=branch%3Amaster"><img src="https://github.com/imroc/req/actions/workflows/ci.yml/badge.svg" alt="Build Status"></a>
        <a href="https://goreportcard.com/report/github.com/imroc/req/v3"><img src="https://goreportcard.com/badge/github.com/imroc/req/v3" alt="Go Report Card"></a>
        <a href="https://pkg.go.dev/github.com/imroc/req/v3"><img src="https://pkg.go.dev/badge/github.com/imroc/req/v3.svg"></a>
        <a href="LICENSE"><img src="https://img.shields.io/github/license/imroc/req.svg" alt="License"></a>
        <a href="https://github.com/imroc/req/releases"><img src="https://img.shields.io/github/v/release/imroc/req?display_name=tag&sort=semver" alt="GitHub Releases"></a>
        <a href="https://github.com/avelino/awesome-go"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Go"></a>
    </p> 
</p>

## Documentation

Full documentation is available on the official website: https://req.cool.

## <a name="Features">Features</a>

* **Simple and Powerful**: Simple and easy to use, providing rich client-level and request-level settings, all of which are intuitive and chainable methods.
* **Easy Debugging**: Powerful and convenient debug utilities, including debug logs, performance traces, and even dump the complete request and response content (see [Debugging](https://req.cool/docs/tutorial/debugging/)).
* **Easy API Testing**: API testing can be done with minimal code, no need to explicitly create any Request or Client, or even to handle errors (See [Quick HTTP Test](https://req.cool/docs/tutorial/quick-test/))
* **Smart by Default**: Detect and decode to utf-8 automatically if possible to avoid garbled characters (See [Auto Decode](https://req.cool/docs/tutorial/auto-decode/)), marshal request body and unmarshal response body automatically according to the Content-Type.
* **Support Multiple HTTP Versions**: Support `HTTP/1.1`, `HTTP/2`, and `HTTP/3`, and can automatically detect the server side and select the optimal HTTP version for requests, you can also force the protocol if you want (See [Force HTTP version](https://req.cool/docs/tutorial/force-http-version/)).
* **Support Retry**: Support automatic request retry and is fully customizable (See [Retry](https://req.cool/docs/tutorial/retry/)).
* **HTTP Fingerprinting**: Support http fingerprint impersonation, so that we can access websites that prohibit crawler programs by identifying http fingerprints (See [HTTP Fingerprint](https://req.cool/docs/tutorial/http-fingerprint/)).
* **Multiple Authentication Methods**: You can use HTTP Basic Auth, Bearer Auth Token and Digest Auth out of box (see [Authentication](https://req.cool/docs/tutorial/authentication/)).
* **Easy Download and Upload**: You can download and upload files with simple request settings, and even set a callback to show real-time progress (See [Download](https://req.cool/docs/tutorial/download/) and [Upload](https://req.cool/docs/tutorial/upload/)).
* **Exportable**: `req.Transport` is exportable. Compared with `http.Transport`, it also supports HTTP3, dump content, middleware, etc. It can directly replace the Transport of `http.Client` in existing projects, and obtain more powerful functions with minimal code change.
* **Extensible**: Support Middleware for Request, Response, Client and Transport (See [Request and Response Middleware](https://req.cool/docs/tutorial/middleware-for-request-and-response/)) and [Client and Transport Middleware](https://req.cool/docs/tutorial/middleware-for-client-and-transport/)).

## <a name="Get-Started">Get Started</a>

**Install**

You first need [Go](https://go.dev/) installed (version 1.24+ is required), then you can use the below Go command to install req:

``` sh
go get github.com/imroc/req/v3
```

**Import**

Import req to your code:

```go
import "github.com/imroc/req/v3"
```

**Basic Usage**

```bash
# assume the following codes in main.go file
$ cat main.go
```

```go
package main

import (
    "github.com/imroc/req/v3"
)

func main() {
    req.DevMode() // Treat the package name as a Client, enable development mode
    req.MustGet("https://httpbin.org/uuid") // Treat the package name as a Request, send GET request.

    req.EnableForceHTTP1() // Force using HTTP/1.1
    req.MustGet("https://httpbin.org/uuid")
}
```

```bash
$ go run main.go
2022/05/19 10:05:07.920113 DEBUG [req] HTTP/2 GET https://httpbin.org/uuid
:authority: httpbin.org
:method: GET
:path: /uuid
:scheme: https
user-agent: req/v3 (https://github.com/imroc/req/v3)
accept-encoding: gzip

:status: 200
date: Thu, 19 May 2022 02:05:08 GMT
content-type: application/json
content-length: 53
server: gunicorn/19.9.0
access-control-allow-origin: *
access-control-allow-credentials: true

{
  "uuid": "bd519208-35d1-4483-ad9f-e1555ae108ba"
}

2022/05/19 10:05:09.340974 DEBUG [req] HTTP/1.1 GET https://httpbin.org/uuid
GET /uuid HTTP/1.1
Host: httpbin.org
User-Agent: req/v3 (https://github.com/imroc/req/v3)
Accept-Encoding: gzip

HTTP/1.1 200 OK
Date: Thu, 19 May 2022 02:05:09 GMT
Content-Type: application/json
Content-Length: 53
Connection: keep-alive
Server: gunicorn/19.9.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

{
  "uuid": "49b7f916-c6f3-49d4-a6d4-22ae93b71969"
}
```

The sample code above is good for quick testing purposes, which use `DevMode()` to see request details, and send requests using global wrapper methods that use the default client behind the scenes to initiate the request.

In production, it is recommended to explicitly create a client, and then use the same client to send all requests, please see other examples below.

**Videos**

The following is a series of video tutorials for req:

* [Youtube Play List](https://www.youtube.com/watch?v=Dy8iph8JWw0&list=PLnW6i9cc0XqlhUgOJJp5Yf1FHXlANYMhF&index=2)
* [BiliBili 播放列表](https://www.bilibili.com/video/BV14t4y1J7cm) (Chinese)

**More**

Check more introduction, tutorials, examples, best practices and API references on the [official website](https://req.cool/).

## <a name="Simple-Get">Simple GET</a>

```go
package main

import (
	"fmt"
	"github.com/imroc/req/v3"
	"log"
)

func main() {
	client := req.C() // Use C() to create a client.
	resp, err := client.R(). // Use R() to create a request.
		Get("https://httpbin.org/uuid")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp)
}
```

```txt
{
  "uuid": "a4d4430d-0e5f-412f-88f5-722d84bc2a62"
}
```

## <a name="Advanced-Get">Advanced GET</a>

```go
package main

import (
  "fmt"
  "github.com/imroc/req/v3"
  "log"
  "time"
)

type ErrorMessage struct {
  Message string `json:"message"`
}

type UserInfo struct {
  Name string `json:"name"`
  Blog string `json:"blog"`
}

func main() {
  client := req.C().
    SetUserAgent("my-custom-client"). // Chainable client settings.
    SetTimeout(5 * time.Second)

  var userInfo UserInfo
  var errMsg ErrorMessage
  resp, err := client.R().
    SetHeader("Accept", "application/vnd.github.v3+json"). // Chainable request settings.
    SetPathParam("username", "imroc"). // Replace path variable in url.
    SetSuccessResult(&userInfo). // Unmarshal response body into userInfo automatically if status code is between 200 and 299.
    SetErrorResult(&errMsg). // Unmarshal response body into errMsg automatically if status code >= 400.
    EnableDump(). // Enable dump at request level, only print dump content if there is an error or some unknown situation occurs to help troubleshoot.
    Get("https://api.github.com/users/{username}")

  if err != nil { // Error handling.
    log.Println("error:", err)
    log.Println("raw content:")
    log.Println(resp.Dump()) // Record raw content when error occurs.
    return
  }

  if resp.IsErrorState() { // Status code >= 400.
    fmt.Println(errMsg.Message) // Record error message returned.
    return
  }

  if resp.IsSuccessState() { // Status code is between 200 and 299.
    fmt.Printf("%s (%s)\n", userInfo.Name, userInfo.Blog)
    return
  }

  // Unknown status code.
  log.Println("unknown status", resp.Status)
  log.Println("raw content:")
  log.Println(resp.Dump()) // Record raw content when server returned unknown status code.
}
```

Normally it will output (SuccessState):

```txt
roc (https://imroc.cc)
```

## <a name="More-Advanced-Get">More Advanced GET</a>

You can set up a unified logic for error handling on the client, so that each time you send a request you only need to focus on the success situation, reducing duplicate code.

```go
package main

import (
	"fmt"
	"github.com/imroc/req/v3"
	"log"
	"time"
)

type ErrorMessage struct {
	Message string `json:"message"`
}

func (msg *ErrorMessage) Error() string {
	return fmt.Sprintf("API Error: %s", msg.Message)
}

type UserInfo struct {
	Name string `json:"name"`
	Blog string `json:"blog"`
}

var client = req.C().
	SetUserAgent("my-custom-client"). // Chainable client settings.
	SetTimeout(5 * time.Second).
	EnableDumpEachRequest().
	SetCommonErrorResult(&ErrorMessage{}).
	OnAfterResponse(func(client *req.Client, resp *req.Response) error {
		if resp.Err != nil { // There is an underlying error, e.g. network error or unmarshal error.
			return nil
		}
		if errMsg, ok := resp.ErrorResult().(*ErrorMessage); ok {
			resp.Err = errMsg // Convert api error into go error
			return nil
		}
		if !resp.IsSuccessState() {
			// Neither a success response nor a error response, record details to help troubleshooting
			resp.Err = fmt.Errorf("bad status: %s\nraw content:\n%s", resp.Status, resp.Dump())
		}
		return nil
	})

func main() {
	var userInfo UserInfo
	resp, err := client.R().
		SetHeader("Accept", "application/vnd.github.v3+json"). // Chainable request settings
		SetPathParam("username", "imroc").
		SetSuccessResult(&userInfo). // Unmarshal response body into userInfo automatically if status code is between 200 and 299.
		Get("https://api.github.com/users/{username}")

	if err != nil { // Error handling.
		log.Println("error:", err)
		return
	}

	if resp.IsSuccessState() { // Status code is between 200 and 299.
		fmt.Printf("%s (%s)\n", userInfo.Name, userInfo.Blog)
	}
}
```

## <a name="Simple-Post">Simple POST</a>

```go
package main

import (
  "fmt"
  "github.com/imroc/req/v3"
  "log"
)

type Repo struct {
  Name string `json:"name"`
  Url  string `json:"url"`
}

type Result struct {
  Data string `json:"data"`
}

func main() {
  client := req.C().DevMode()
  var result Result

  resp, err := client.R().
    SetBody(&Repo{Name: "req", Url: "https://github.com/imroc/req"}).
    SetSuccessResult(&result).
    Post("https://httpbin.org/post")
  if err != nil {
    log.Fatal(err)
  }

  if !resp.IsSuccessState() {
    fmt.Println("bad response status:", resp.Status)
    return
  }
  fmt.Println("++++++++++++++++++++++++++++++++++++++++++++++++")
  fmt.Println("data:", result.Data)
  fmt.Println("++++++++++++++++++++++++++++++++++++++++++++++++")
}
```

```txt
2022/05/19 20:11:00.151171 DEBUG [req] HTTP/2 POST https://httpbin.org/post
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
user-agent: req/v3 (https://github.com/imroc/req/v3)
content-type: application/json; charset=utf-8
content-length: 55
accept-encoding: gzip

{"name":"req","website":"https://github.com/imroc/req"}

:status: 200
date: Thu, 19 May 2022 12:11:00 GMT
content-type: application/json
content-length: 651
server: gunicorn/19.9.0
access-control-allow-origin: *
access-control-allow-credentials: true

{
  "args": {},
  "data": "{\"name\":\"req\",\"website\":\"https://github.com/imroc/req\"}",
  "files": {},
  "form": {},
  "headers": {
    "Accept-Encoding": "gzip",
    "Content-Length": "55",
    "Content-Type": "application/json; charset=utf-8",
    "Host": "httpbin.org",
    "User-Agent": "req/v3 (https://github.com/imroc/req/v3)",
    "X-Amzn-Trace-Id": "Root=1-628633d4-7559d633152b4307288ead2e"
  },
  "json": {
    "name": "req",
    "website": "https://github.com/imroc/req"
  },
  "origin": "103.7.29.30",
  "url": "https://httpbin.org/post"
}

++++++++++++++++++++++++++++++++++++++++++++++++
data: {"name":"req","url":"https://github.com/imroc/req"}
++++++++++++++++++++++++++++++++++++++++++++++++
```

## <a name="Do-API-Style">Do API Style</a>

If you like, you can also use a Do API style like the following to make requests:

```go
package main

import (
	"fmt"
	"github.com/imroc/req/v3"
)

type APIResponse struct {
	Origin string `json:"origin"`
	Url    string `json:"url"`
}

func main() {
	var resp APIResponse
	c := req.C().SetBaseURL("https://httpbin.org/post")
	err := c.Post().
		SetBody("hello").
		Do().
		Into(&resp)
	if err != nil {
		panic(err)
	}
	fmt.Println("My IP is", resp.Origin)
}
```

```txt
My IP is 182.138.155.113
```

* The order of chain calls is more intuitive: first call Client to create a request with a specified Method, then use chain calls to set the request, then use `Do()` to fire the request, return Response, and finally call `Response.Into` to unmarshal response body into specified object.
* `Response.Into` will return an error if an error occurs during sending the request or during unmarshalling.
* The url of some APIs is fixed, and different types of requests are implemented by passing different bodies. In this scenario, `Client.SetBaseURL` can be used to set a unified url, and there is no need to set the url for each request when initiating a request. Of course, you can also call `Request.SetURL` to set it if you need it.

## <a name="Build-SDK-With-Req">Build SDK With Req</a>

Here is an example of building GitHub's SDK with req, using two styles (`GetUserProfile_Style1`, `GetUserProfile_Style2`).

```go
import (
	"context"
	"fmt"
	"github.com/imroc/req/v3"
)

type ErrorMessage struct {
	Message string `json:"message"`
}

// Error implements go error interface.
func (msg *ErrorMessage) Error() string {
	return fmt.Sprintf("API Error: %s", msg.Message)
}

type GithubClient struct {
	*req.Client
}

func NewGithubClient() *GithubClient {
	return &GithubClient{
		Client: req.C().
			SetBaseURL("https://api.github.com").
			SetCommonErrorResult(&ErrorMessage{}).
			EnableDumpEachRequest().
			OnAfterResponse(func(client *req.Client, resp *req.Response) error {
				if resp.Err != nil { // There is an underlying error, e.g. network error or unmarshal error.
					return nil
				}
				if errMsg, ok := resp.ErrorResult().(*ErrorMessage); ok {
					resp.Err = errMsg // Convert api error into go error
					return nil
				}
				if !resp.IsSuccessState() {
					// Neither a success response nor a error response, record details to help troubleshooting
					resp.Err = fmt.Errorf("bad status: %s\nraw content:\n%s", resp.Status, resp.Dump())
				}
				return nil
			}),
	}
}

type UserProfile struct {
	Name string `json:"name"`
	Blog string `json:"blog"`
}

// GetUserProfile_Style1 returns the user profile for the specified user.
// Github API doc: https://docs.github.com/en/rest/users/users#get-a-user
func (c *GithubClient) GetUserProfile_Style1(ctx context.Context, username string) (user *UserProfile, err error) {
	_, err = c.R().
		SetContext(ctx).
		SetPathParam("username", username).
		SetSuccessResult(&user).
		Get("/users/{username}")
	return
}

// GetUserProfile_Style2 returns the user profile for the specified user.
// Github API doc: https://docs.github.com/en/rest/users/users#get-a-user
func (c *GithubClient) GetUserProfile_Style2(ctx context.Context, username string) (user *UserProfile, err error) {
	err = c.Get("/users/{username}").
		SetPathParam("username", username).
		Do(ctx).
		Into(&user)
	return
}
```

## Go Version Compatibility Matrix

| Req Version | Go Version |
| ----------- | ---------- |
| 3.53.0      | 1.24+      |
| 3.51.0      | 1.23+      |
| 3.43.0      | 1.21+      |
| 3.41.0      | 1.20+      |

## Contributing

If you have a bug report or feature request, you can [open an issue](https://github.com/imroc/req/issues/new), and [pull requests](https://github.com/imroc/req/pulls) are also welcome.

## Contact

If you have questions, feel free to reach out to us in the following ways:

* [Github Discussion](https://github.com/imroc/req/discussions)
* [Slack](https://imroc-req.slack.com/archives/C03UFPGSNC8) | [Join](https://slack.req.cool/)

## Sponsors

If you like req and it really helps you, feel free to reward me with a cup of coffee, and don't forget to mention your github id.

<table>
    <tr>
        <td align="center">
            <img src="https://req.cool/images/wechat.jpg" width="200px"   alt=""/>
            <br />
            <sub><b>Wechat</b></sub>
        </td>
        <td align="center">
            <img src="https://req.cool/images/alipay.jpg" width="200px"   alt=""/>
            <br />
            <sub><b>Alipay</b></sub>
        </td>
    </tr>
</table>

Many thanks to the following sponsors:

<table>
    <tr>
        <td align="center">
            <a href="https://github.com/M-Cosmosss">
                <img src="https://avatars.githubusercontent.com/u/46757262?v=4?s=100" width="160px"   alt=""/>
                <br />
                <sub><b>M-Cosmosss 🥇</b></sub>
            </a>
        </td>
        <td align="center">
            <a href="https://github.com/aadog">
                <img src="https://avatars.githubusercontent.com/u/18098725?v=4?s=100" width="160px"   alt=""/>
                <br />
                <sub><b>aadog 🥈</b></sub>
            </a>
        </td>
    </tr>
</table>

## <a name="License">License</a>

`Req` released under MIT license, refer [LICENSE](LICENSE) file.


HTTP client for golang. If you have experience about axios or requests, you will love it. No 3rd dependency

# Request [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) [![Go Report Card](https://goreportcard.com/badge/github.com/monaco-io/request)](https://goreportcard.com/report/github.com/monaco-io/request) ![Go](https://github.com/monaco-io/request/workflows/Go/badge.svg)

## Stargazers over time
[![Stargazers over time](https://starchart.cc/monaco-io/request.svg?variant=adaptive)](https://starchart.cc/monaco-io/request)

<img align="right" width="159px" src="https://raw.githubusercontent.com/gin-gonic/logo/master/color.png">

[![GoDoc](https://godoc.org/github.com/monaco-io/request?status.svg)](https://pkg.go.dev/github.com/monaco-io/request?tab=doc)
[![codecov](https://codecov.io/gh/monaco-io/request/branch/master/graph/badge.svg)](https://codecov.io/gh/monaco-io/request)
[![Release](https://img.shields.io/github/release/monaco-io/request.svg?style=flat-square)](https://github.com/monaco-io/request/releases)
[![TODOs](https://badgen.net/https/api.tickgit.com/badgen/github.com/monaco-io/request)](https://www.tickgit.com/browse?repo=github.com/monaco-io/request)
[![License](https://img.shields.io/github/license/monaco-io/request?style=plastic)](https://github.com/monaco-io/request/blob/master/LICENSE)





HTTP Client for golang, Inspired by [Javascript-axios](https://github.com/axios/axios) [Python-request](https://github.com/psf/requests).
If you have experience about axios or requests, you will love it.
No 3rd dependency.

## Features

- Make [http](https://golang.org) requests from Golang
- Transform request and response data

## Installing

go mod:

```bash
go get github.com/monaco-io/request
```

## Methods

- OPTIONS
- GET
- HEAD
- POST
- PUT
- DELETE
- TRACE
- CONNECT

## Example

### POST

```go
package main

import (
    "github.com/monaco-io/request"
)

func main() {
    var body = struct {
         A string
         B int
        }{A: "A", B: 1}
    var result interface{}

    c := request.Client{
        URL:    "https://google.com",
        Method: "POST",
        Query: map[string]string{"hello": "world"},
        JSON:   body,
    }
    resp := c.Send().Scan(&result)
    if !resp.OK(){
        // handle error
        log.Println(resp.Error())
    }

    // str := resp.String()
    // bytes := resp.Bytes()
```

### POST with local files

```go
package main

import (
    "github.com/monaco-io/request"
)

func main() {
    c := request.Client{
        URL:    "https://google.com",
        Method: "POST",
        Query: map[string]string{"hello": "world"},
        MultipartForm: MultipartForm{
            Fields: map[string]string{"a": "1"},
			Files:  []string{"doc.txt"},
        },
    }
    resp := c.Send().Scan(&result)
    ...
```

### POST step by step

```go
package main

import (
    "github.com/monaco-io/request"
)

func main() {
    var response interface{}

    resp := request.
        New().
        POST("http://httpbin.org/post").
        AddHeader(map[string]string{"Google": "google"}).
        AddBasicAuth("google", "google").
        AddURLEncodedForm(map[string]string{"data": "google"}).
        Send().
        Scan(&response)
    ...
```

### POST with context (1/2)

```go
package main

import (
    "github.com/monaco-io/request"
    "context"
)

func main() {
    c := request.Client{
        Context: context.Background(),
        URL:       "https://google.com",
        Method:    "POST",
        BasicAuth: request.BasicAuth{
            Username: "google",
            Password: "google",
        },
    }
    resp := c.Send()
    ...
```

### POST with context (2/2)

```go
package main

import (
    "github.com/monaco-io/request"
    "context"
)

func main() {
    var response interface{}

    resp := request.
        NewWithContext(context.TODO()).
        POST("http://httpbin.org/post").
        AddHeader(map[string]string{"Google": "google"}).
        AddBasicAuth("google", "google").
        AddURLEncodedForm(map[string]string{"data": "google"}).
        Send().
        Scan(&response)
    ...
```

### Authorization

```go
package main

import (
    "github.com/monaco-io/request"
)

func main() {
    c := request.Client{
        URL:       "https://google.com",
        Method:    "POST",
        BasicAuth: request.BasicAuth{
            Username: "google",
            Password: "google",
        },
    }
    resp := c.Send()
}
```

### Timeout

```go
package main

import (
    "github.com/monaco-io/request"
)

func main() {
    c := request.Client{
        URL:       "https://google.com",
        Method:    "POST",
        Timeout:   time.Second*10,
    }
}
```

### Cookies

```go
package main

import (
    "github.com/monaco-io/request"
)

func main() {
    c := request.Client{
        URL:       "https://google.com",
        CookiesMap: map[string]string{
            "cookie_name": "cookie_value",
        }
    }
}
```

### TLS

```go
package main

import (

    "github.com/monaco-io/request"
)

func main() {
    c := request.Client{
        URL:       "https://google.com",
        TLSConfig: &tls.Config{InsecureSkipVerify: true},
    }
}
```

## License

[MIT](LICENSE)

request

Hit your API targets with rapid-fire precision using Go's fastest and simple HTTP Client

<div align="center">
    <img src="docs/assets/images/logo.png" alt="Logo fast-shot" width="320"/>
    <hr />
    <p>A Fluent Go REST Client Library</p>
    <p>
        <a href="https://goreportcard.com/report/opus-domini/fast-shot"><img src="https://goreportcard.com/badge/opus-domini/fast-shot" alt="Go Report Badge"></a>
        <a href="https://godoc.org/github.com/opus-domini/fast-shot"><img src="https://godoc.org/github.com/opus-domini/fast-shot?status.svg" alt="Go Doc Badge"></a>    
        <a href="https://github.com/opus-domini/fast-shot/actions/workflows/ci.yml"><img src="https://github.com/opus-domini/fast-shot/actions/workflows/ci.yml/badge.svg" alt="CI Badge"></a>
        <a href="https://codecov.io/gh/opus-domini/fast-shot"><img src="https://codecov.io/gh/opus-domini/fast-shot/graph/badge.svg?token=C80QDL5W7T" alt="Codecov Badge"/></a>        
        <a href="https://github.com/opus-domini/fast-shot/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opus-domini/fast-shot.svg" alt="License Badge"></a>
        <a href="https://github.com/avelino/awesome-go"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Go"></a>
    </p>
</div>

Fast Shot is a robust, feature-rich, and highly configurable HTTP client for Go. Crafted with modern Go practices in mind, it offers a fluent, chainable API that allows for clean, idiomatic code.

## Table of Contents

- [Why Fast Shot?](#why-fast-shot)
- [Features](#features-)
- [Installation](#installation-)
- [Quick Start](#quick-start-)
- [Advanced Usage](#advanced-usage-)
- [Contributing](#contributing-)

## Why Fast Shot?

* **Fluent & Chainable API**: Write expressive, readable, and flexible HTTP client code.
* **Ease of Use**: Reduce boilerplate, making HTTP requests as straightforward as possible.
* **Rich Features**: From headers to query parameters and JSON support, Fast Shot covers your needs.
* **Advanced Retry Mechanism**: Built-in support for retries with various backoff strategies.

## Features 🌟

* Fluent and chainable API for clean, expressive code
* Comprehensive HTTP method support (GET, POST, PUT, DELETE, etc.)
* Flexible authentication options (Bearer Token, Basic Auth, Custom)
* Easy manipulation of headers, cookies, and query parameters
* Advanced retry mechanism with customizable backoff strategies
* Pre-request and post-response hooks for observability and custom logic
* Client-side load balancing for improved reliability
* JSON request and response support
* XML request and response support
* Timeout and redirect control
* Proxy support
* Extensible and customizable for specific needs
* Well-tested and production-ready

## Installation 🔧

To install Fast Shot, run the following command:

```bash 
go get github.com/opus-domini/fast-shot
```

## Quick Start 🚀

Here's how you can make a simple POST using Fast Shot:

```go
package main

import (
    "fmt"
    fastshot "github.com/opus-domini/fast-shot"
    "github.com/opus-domini/fast-shot/constant/mime"
)

func main() {
    client := fastshot.NewClient("https://api.example.com").
        Auth().BearerToken("your_token_here").
        Build()

    payload := map[string]interface{}{
        "key1": "value1",
        "key2": "value2",
    }

    response, err := client.POST("/endpoint").
        Header().AddAccept(mime.JSON).
        Body().AsJSON(payload).
        Send()

    // Check for request send problems.
    if err != nil {
        panic(err) // (¬_¬")
    }

    // Check for (4xx || 5xx) errors response.
    if response.Status().IsError() {
        panic(response.Body().AsString()) // ¯\_(ツ)_/¯
    }
	
    var result map[string]interface{}
    _ := response.Body().AsJSON(&result)

    // Congrats! Do something awesome with the result (¬‿¬)
}
```

## Advanced Usage 🤖

### Fluent API

Easily chain multiple settings in a single line:

```go 
client := fastshot.NewClient("https://api.example.com").
    Auth().BearerToken("your-bearer-token").
    Header().Add("My-Header", "My-Value").
    Config().SetTimeout(30 * time.Second).
    Build()
```
### Advanced Retry Mechanism

Handle transient failures with customizable backoff strategies:

```go 
client.POST("/resource").
    Retry().SetExponentialBackoff(2 * time.Second, 5, 2.0).
    Send()
```

This new retry feature supports:
- Constant backoff
- Exponential backoff
- Full jitter for both constant and exponential backoff
- Custom retry conditions
- Maximum delay setting

### Request Hooks

Inject custom logic before sending requests and after receiving responses. Useful for logging, metrics, tracing, request signing, and audit logs:

```go
client := fastshot.NewClient("https://api.example.com").
    Hook().OnBeforeRequest(func(req *http.Request) error {
        req.Header.Set("X-Request-ID", generateID())
        return nil
    }).
    Hook().OnAfterResponse(func(req *http.Request, resp *http.Response) {
        log.Printf("%s %s → %d", req.Method, req.URL, resp.StatusCode)
    }).
    Build()
```

Hooks can also be set per-request:

```go
client.GET("/resource").
    Hook().OnBeforeRequest(func(req *http.Request) error {
        // Only for this request
        return nil
    }).
    Send()
```

Key behaviors:
- Client hooks run before request hooks (same ordering as headers and cookies)
- Hooks run on every attempt, including retries
- A before-request hook returning an error aborts the request
- After-response hooks are observational and do not return errors

### Out-of-the-Box Support for Client Load Balancing

Effortlessly manage multiple endpoints:

```go
client := fastshot.NewClientLoadBalancer([]string{
    "https://api1.example.com",
    "https://api2.example.com",
    "https://api3.example.com",
    }).
    Config().SetTimeout(time.Second * 10).
    Build()
```

This feature allows you to distribute network traffic across several servers, enhancing the performance and reliability of your applications.

### Authentication

Fast Shot supports various types of authentication:

```go
// Bearer Token
builder.Auth().BearerToken("your-bearer-token")

// Basic Authentication
builder.Auth().BasicAuth("username", "password")

// Custom Authentication
builder.Auth().Set("custom-authentication-header")
```

### Custom Headers and Cookies

Add your own headers and cookies effortlessly:

```go 
// Add Custom Header
builder.Header().
    Add("header", "value")

// Add Multiple Custom Headers
builder.Header().
    AddAll(map[string]string{
        "key1": "value1",
        "key2": "value2",
        "key3": "value3",
    })

// Add Custom Cookie
builder.Cookie().
    Add(&http.Cookie{Name: "session_id", Value: "id"})
```

### Advanced Configurations

Control every aspect of the HTTP client:

```go
// Set Timeout
builder.Config().
    SetTimeout(time.Second * 30)

// Set Follow Redirect
builder.Config().
    SetFollowRedirects(false)

// Set Custom Transport
builder.Config().
    SetCustomTransport(myCustomTransport)

// Set Proxy
builder.Config().
    SetProxy("http://my-proxy-server:port")
```

### Response Handling

Extract information from the response with ease:

```go
// Fluent response status check
response.Status()

// Easy response body access and conversion
response.Body()

// Get response headers to inspect
response.Header()

// Get response cookies for further processing 
response.Cookie()

// Get raw response if needed
response.Raw()

// and more...
```

## Contributing 🤝

We welcome contributions to Fast Shot! Here's how you can contribute:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Write your code and tests
4. Ensure all tests pass
5. Submit a pull request

Please make sure to update tests as appropriate and adhere to the existing coding style.

For more detailed information, check out our [CONTRIBUTING.md](https://github.com/opus-domini/fast-shot/blob/main/CONTRIBUTING.md) file.

## Stargazers over time ⭐

[![Stargazers over time](https://starchart.cc/opus-domini/fast-shot.svg?variant=adaptive)](https://starchart.cc/opus-domini/fast-shot)


fast-shot

Get easily stdlib HTTP client, which does not share any state with other clients

# cleanhttp

Functions for accessing "clean" Go http.Client values

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

The Go standard library contains a default `http.Client` called
`http.DefaultClient`. It is a common idiom in Go code to start with
`http.DefaultClient` and tweak it as necessary, and in fact, this is
encouraged; from the `http` package documentation:

> The Client's Transport typically has internal state (cached TCP connections),
so Clients should be reused instead of created as needed. Clients are safe for
concurrent use by multiple goroutines.

Unfortunately, this is a shared value, and it is not uncommon for libraries to
assume that they are free to modify it at will. With enough dependencies, it
can be very easy to encounter strange problems and race conditions due to
manipulation of this shared value across libraries and goroutines (clients are
safe for concurrent use, but writing values to the client struct itself is not
protected).

Making things worse is the fact that a bare `http.Client` will use a default
`http.Transport` called `http.DefaultTransport`, which is another global value
that behaves the same way. So it is not simply enough to replace
`http.DefaultClient` with `&http.Client{}`.

This repository provides some simple functions to get a "clean" `http.Client`
-- one that uses the same default values as the Go standard library, but
returns a client that does not share any state with other clients.


go-cleanhttp

A Go HTTP client library inspired by Axios, providing a simple and intuitive API for making HTTP requests

# axios4go

[![Go Reference](https://pkg.go.dev/badge/github.com/rezmoss/axios4go.svg)](https://pkg.go.dev/github.com/rezmoss/axios4go)
[![Go Report Card](https://goreportcard.com/badge/github.com/rezmoss/axios4go)](https://goreportcard.com/report/github.com/rezmoss/axios4go)
[![Release](https://img.shields.io/github/v/release/rezmoss/axios4go.svg?style=flat-square)](https://github.com/rezmoss/axios4go/releases)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9401/badge)](https://www.bestpractices.dev/projects/9401)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

axios4go is a Go HTTP client library inspired by [Axios](https://github.com/axios/axios) (a promise based HTTP client for node.js), providing a simple and intuitive API for making HTTP requests. It offers features like JSON handling, configurable instances, and support for various HTTP methods.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
  - [Making a Simple Request](#making-a-simple-request)
  - [Using Request Options](#using-request-options)
  - [Making POST Requests](#making-post-requests)
  - [Using Async Requests](#using-async-requests)
  - [Creating a Custom Client](#creating-a-custom-client)
  - [Using Interceptors](#using-interceptors)
  - [Handling Progress](#handling-progress)
  - [Using Proxy](#using-proxy)
  - [Response Caching](#response-caching)
- [Configuration Options](#configuration-options)
- [Contributing](#contributing)
- [License](#license)

## Features

- Simple and intuitive API
- Support for `GET`, `POST`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`, and `PATCH` methods
- JSON request and response handling
- Configurable client instances
- Global and per-request timeout management
- Redirect management
- Basic authentication support
- Customizable request options
- Promise-like asynchronous requests
- Request and response interceptors
- Upload and download progress tracking
- Proxy support
- Configurable max content length and body length
- Response caching with pluggable storage backends

## Installation

To install `axios4go`, use `go get`:

```bash
go get -u github.com/rezmoss/axios4go
```

**Note**: Requires Go 1.13 or later.

## Usage

### Making a Simple Request

```go
package main

import (
    "fmt"

    "github.com/rezmoss/axios4go"
)

func main() {
    resp, err := axios4go.Get("https://api.example.com/data")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    fmt.Printf("Status Code: %d\n", resp.StatusCode)
    fmt.Printf("Body: %s\n", string(resp.Body))
}
```

### Using Request Options

```go
resp, err := axios4go.Get("https://api.example.com/data", &axios4go.RequestOptions{
    Headers: map[string]string{
        "Authorization": "Bearer token",
    },
    Params: map[string]string{
        "query": "golang",
    },
})
```

### Making POST Requests

```go
body := map[string]interface{}{
    "name": "John Doe",
    "age":  30,
}
resp, err := axios4go.Post("https://api.example.com/users", body)
if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
}
fmt.Printf("Status Code: %d\n", resp.StatusCode)
fmt.Printf("Body: %s\n", string(resp.Body))
```

### Using Async Requests

```go
axios4go.GetAsync("https://api.example.com/data").
    Then(func(response *axios4go.Response) {
        fmt.Printf("Status Code: %d\n", response.StatusCode)
        fmt.Printf("Body: %s\n", string(response.Body))
    }).
    Catch(func(err error) {
        fmt.Printf("Error: %v\n", err)
    }).
    Finally(func() {
        fmt.Println("Request completed")
    })
```

### Creating a Custom Client

```go
client := axios4go.NewClient("https://api.example.com")

resp, err := client.Request(&axios4go.RequestOptions{
    Method: "GET",
    URL:    "/users",
    Headers: map[string]string{
        "Authorization": "Bearer token",
    },
})
if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
}
fmt.Printf("Status Code: %d\n", resp.StatusCode)
fmt.Printf("Body: %s\n", string(resp.Body))
```

### Using Interceptors

```go
options := &axios4go.RequestOptions{
    InterceptorOptions: axios4go.InterceptorOptions{
        RequestInterceptors: []func(*http.Request) error{
            func(req *http.Request) error {
                req.Header.Set("X-Custom-Header", "value")
                return nil
            },
        },
        ResponseInterceptors: []func(*http.Response) error{
            func(resp *http.Response) error {
                fmt.Printf("Response received with status: %d\n", resp.StatusCode)
                return nil
            },
        },
    },
}

resp, err := axios4go.Get("https://api.example.com/data", options)
```

### Handling Progress

```go
options := &axios4go.RequestOptions{
    OnUploadProgress: func(bytesRead, totalBytes int64) {
        fmt.Printf("Upload progress: %d/%d bytes\n", bytesRead, totalBytes)
    },
    OnDownloadProgress: func(bytesRead, totalBytes int64) {
        fmt.Printf("Download progress: %d/%d bytes\n", bytesRead, totalBytes)
    },
}

resp, err := axios4go.Post("https://api.example.com/upload", largeData, options)
```

### Using Proxy

```go
options := &axios4go.RequestOptions{
    Proxy: &axios4go.Proxy{
        Protocol: "http",
        Host:     "proxy.example.com",
        Port:     8080,
        Auth: &axios4go.Auth{
            Username: "proxyuser",
            Password: "proxypass",
        },
    },
}

resp, err := axios4go.Get("https://api.example.com/data", options)
```

### Response Caching

axios4go supports response caching to reduce network calls. Caching is opt-in and disabled by default.

#### Basic Usage

```go
import (
    "time"
    "github.com/rezmoss/axios4go"
)

// Create a memory cache
cache := axios4go.NewMemoryCache(&axios4go.MemoryCacheOptions{
    MaxSize:         1000,              // Max entries (0 = unlimited)
    CleanupInterval: 5 * time.Minute,   // Cleanup expired entries
})
defer cache.Close()

// Create client with cache
client := axios4go.NewClientWithCache("https://api.example.com", &axios4go.CacheConfig{
    Cache:      cache,
    DefaultTTL: 5 * time.Minute,
})

// Enable caching for a request
resp, err := client.Request(&axios4go.RequestOptions{
    Method: "GET",
    URL:    "/users",
    Cache:  axios4go.CacheEnabled(10 * time.Minute),
})
```

#### Force Refresh

```go
// Bypass cache and fetch fresh data
resp, err := client.Request(&axios4go.RequestOptions{
    Method: "GET",
    URL:    "/users",
    Cache: &axios4go.RequestCacheOptions{
        Enabled:      axios4go.Bool(true),
        TTL:          5 * time.Minute,
        ForceRefresh: true,
    },
})
```

#### Custom Cache Key

```go
// Use custom key function to include headers in cache key
client := axios4go.NewClientWithCache("https://api.example.com", &axios4go.CacheConfig{
    Cache:      cache,
    DefaultTTL: 5 * time.Minute,
    KeyFunc: func(method, fullURL string, headers map[string]string) string {
        return method + ":" + fullURL + ":" + headers["Authorization"]
    },
})
```

#### Cache Statistics

```go
stats := client.CacheStats()
fmt.Printf("Hits: %d, Misses: %d, Size: %d\n", stats.Hits, stats.Misses, stats.Size)

// Clear cache
client.ClearCache()
```

#### Custom Cache Implementation

Implement the `Cache` interface for custom storage (Redis, file, etc.):

```go
type Cache interface {
    Get(key string) *CacheEntry
    Set(key string, entry *CacheEntry, ttl time.Duration)
    Delete(key string)
    Clear()
    Stats() CacheStats
}
```

## Configuration Options

`axios4go` supports various configuration options through the `RequestOptions` struct:

- **Method**: HTTP method (`GET`, `POST`, etc.)
- **URL**: Request URL (relative to `BaseURL` if provided)
- **BaseURL**: Base URL for the request (overrides client's `BaseURL` if set)
- **Params**: URL query parameters (`map[string]string`)
- **Body**: Request body (can be `string`, `[]byte`, or any JSON serializable object)
- **Headers**: Custom headers (`map[string]string`)
- **Timeout**: Request timeout in milliseconds
- **Auth**: Basic authentication credentials (`&Auth{Username: "user", Password: "pass"}`)
- **ResponseType**: Expected response type (default is "json")
- **ResponseEncoding**: Expected response encoding (default is "utf8")
- **MaxRedirects**: Maximum number of redirects to follow
- **MaxContentLength**: Maximum allowed response content length
- **MaxBodyLength**: Maximum allowed request body length
- **Decompress**: Whether to decompress the response body (default is true)
- **ValidateStatus**: Function to validate HTTP response status codes
- **InterceptorOptions**: Request and response interceptors
- **Proxy**: Proxy configuration
- **OnUploadProgress**: Function to track upload progress
- **OnDownloadProgress**: Function to track download progress
- **Cache**: Per-request cache configuration (`CacheEnabled(ttl)` or `&RequestCacheOptions{...}`)

**Example**:

```go
options := &axios4go.RequestOptions{
    Method: "POST",
    URL:    "/submit",
    Headers: map[string]string{
        "Content-Type": "application/json",
    },
    Body: map[string]interface{}{
        "title":   "Sample",
        "content": "This is a sample post.",
    },
    Auth: &axios4go.Auth{
        Username: "user",
        Password: "pass",
    },
    Params: map[string]string{
        "verbose": "true",
    },
    Timeout:          5000, // 5 seconds
    MaxRedirects:     5,
    MaxContentLength: 1024 * 1024, // 1MB
    ValidateStatus: func(statusCode int) bool {
        return statusCode >= 200 && statusCode < 300
    },
}

resp, err := client.Request(options)
```

## Contributing

Contributions to `axios4go` are welcome! Please follow these guidelines:

- **Fork the repository** and create a new branch for your feature or bug fix.
- **Ensure your code follows Go conventions** and passes all tests.
- **Write tests** for new features or bug fixes.
- **Submit a Pull Request** with a clear description of your changes.

## License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details

axios4go

An easy-to-use HTTP client 100% in Go to spoof TLS/JA3 and HTTP2 fingerprint

# AzureTLS Client
[![GoDoc](https://godoc.org/github.com/Noooste/azuretls-client?status.svg)](https://godoc.org/github.com/Noooste/azuretls-client)
[![codecov](https://codecov.io/gh/Noooste/azuretls-client/graph/badge.svg?token=XGHX707RK6)](https://codecov.io/gh/Noooste/azuretls-client)
[![build](https://github.com/Noooste/azuretls-client/actions/workflows/push.yml/badge.svg)](https://github.com/Noooste/azuretls-client/actions/workflows/push.yml)
[![Go Report Card](https://goreportcard.com/badge/Noooste/azuretls-client)](https://goreportcard.com/report/Noooste/azuretls-client)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Noooste/azuretls-client/blob/master/LICENSE)

A powerful HTTP client for Go that's **simple to use** but gives you **full control** when you need it.

Perfect for API clients, web scraping, testing, and any situation where you need more than the standard library offers, without the complexity.

## Installation

```bash
go get github.com/Noooste/azuretls-client
```

## Quick Start - 30 Seconds

```go
package main

import (
    "fmt"
    "log"
    "github.com/Noooste/azuretls-client"
)

func main() {
    session := azuretls.NewSession()
    defer session.Close()

    response, err := session.Get("https://api.github.com")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Status: %d\n", response.StatusCode)
    fmt.Println(response.String())
}
```

**That's it!** Just create a session and make requests. This automatically uses Chrome's TLS (JA3) and HTTP/2 fingerprint, making it look like a real browser to servers.

> 💡 **New to Go?** AzureTLS uses a session-based API (similar to creating an `http.Client`). Each session automatically mimics Chrome by default, no fingerprint configuration needed. Advanced customization is completely optional.

## Common Tasks

### POST Request with JSON

```go
session := azuretls.NewSession()
defer session.Close()

data := map[string]string{
    "name": "AzureTLS",
    "type": "HTTP Client",
}

response, err := session.Post("https://api.example.com/data", data)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Status: %d\n", response.StatusCode)
```

### Using a Proxy

```go
session := azuretls.NewSession()
defer session.Close()

// One line proxy setup: supports HTTP, HTTPS, SOCKS4, SOCKS5
err := session.SetProxy("http://username:password@proxy.example.com:8080")
if err != nil {
    log.Fatal(err)
}

response, err := session.Get("https://api.ipify.org")
```

### Browser Emulation

```go
session := azuretls.NewSession()
defer session.Close()

// Default: Chrome fingerprint (already active, no configuration needed!)

// Want to mimic a different browser? Just change it:
session.Browser = azuretls.Firefox  // or Safari, Edge, etc.

response, err := session.Get("https://example.com")
```

### Custom Header Ordering

```go
session := azuretls.NewSession()
defer session.Close()

// Precise control over header order
session.OrderedHeaders = azuretls.OrderedHeaders{
    {"User-Agent", "MyApp/1.0"},
    {"Accept", "application/json"},
    {"Authorization", "Bearer token123"},
}

response, err := session.Get("https://api.example.com")
```

## Why AzureTLS vs Standard Library?

| Feature | net/http | AzureTLS                     |
|---------|----------|------------------------------|
| API Style | Package or Client-based | Session-based                |
| Browser Fingerprint | ❌ Looks like Go | ✅ **Chrome by default**      |
| Cookie Management | Manual setup | ✅ Automatic jar              |
| Ordered Headers | ❌ | ✅ Built-in                   |
| Proxy Support | Manual dialer setup | ✅ `session.SetProxy()`       |
| Multiple Proxy Types | Manual | ✅ HTTP/SOCKS4/SOCKS5         |
| Custom TLS (JA3/JA4) | ❌ | ✅ Easy                       |
| HTTP/2 Customization | ❌ | ✅ Easy                   |
| HTTP/3 Support | ❌ | ✅ Easy                   |
| Browser Presets | ❌ | ✅ Chrome/Firefox/Safari/Edge |


## 🌟 Key Features

- **🌐 Modern Protocols**: HTTP/1.1, HTTP/2, and HTTP/3 support
- **🔧 TLS Fingerprinting**: Full control over ClientHello (JA3/JA4)
- **🎭 Browser Emulation**: Chrome, Firefox, Safari, Edge presets
- **🔗 Advanced Proxy Support**: HTTP, HTTPS, SOCKS4, SOCKS5 with authentication.
- **⛓️ Proxy Chaining**: Multi-hop proxy connections for enhanced anonymity
- **📋 Header Control**: Precise ordering and custom headers
- **🍪 Cookie Management**: Automatic handling with persistent jar
- **🔒 SSL Pinning**: Enhanced security with certificate validation
- **🐛 Debug Tools**: Request logging and dumping capabilities

## Documentation

- 📖 **[Complete API Reference](./examples/README.md)**: Every feature, method, and option
- 💬 **[Examples Directory](./examples/)**: Working code samples
- 🌍 **[CFFI Documentation](./cffi/README.md)**: Use AzureTLS from other languages

### Learn More

- **Making Requests**: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS ([examples/README.md](./examples/README.md#make-requests))
- **TLS Fingerprinting**: JA3/JA4 customization ([examples/README.md](./examples/README.md#modify-tls-client-hello-ja3))
- **HTTP/2 & HTTP/3**: Protocol customization ([examples/README.md](./examples/README.md#modify-http2))
- **Proxy Management**: Advanced proxy features ([examples/README.md](./examples/README.md#proxy))
- **Websockets**: WebSocket support ([examples/README.md](./examples/README.md#websocket))
- **SSL Pinning**: Certificate validation ([examples/README.md](./examples/README.md#ssl-pinning))

## Use Cases

**Perfect for:**
- 🔌 **API Integration**: REST clients that look like real browsers by default
- 🌐 **Web Scraping**: Automatic browser fingerprinting without configuration
- 🛡️ **Testing antibot systems**: Avoid bot detection with authentic browser signatures
- 🔄 **Proxy Rotation**: Built-in support for multiple proxy types
- 🧪 **Security Testing**: Custom TLS configurations for advanced testing
- 📊 **Load Testing**: High-performance concurrent requests

## Multi-Language Support via CFFI

AzureTLS can be used from **any programming language** that supports C Foreign Function Interface.
Read the [CFFI documentation](./cffi/README.md) for full details.

## Community & Support

- 💬 **[GitHub Discussions](https://github.com/Noooste/azuretls-client/discussions)**: Ask questions, share ideas
- 🐛 **[GitHub Issues](https://github.com/Noooste/azuretls-client/issues)**: Report bugs, request features
- 📖 **[Examples](./examples/)**: Code samples and tutorials

## Show Your Support

If AzureTLS helps you build something awesome:

- ⭐ **Star this repository**
- 🐛 **Report bugs** or suggest features
- 💡 **Share your use cases** in discussions
- 🤝 **Contribute** code or documentation
- 🌍 **Create bindings** for your favorite programming language

[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/noste)

## Acknowledgments

Built with ❤️ by the open source community. Special thanks to all [contributors](https://github.com/Noooste/azuretls-client/graphs/contributors).

---

## 🛡️ Need Antibot Bypass?

<a href="https://hypersolutions.co/?utm_source=github&utm_medium=readme&utm_campaign=azure-tls" target="_blank"><img src="./.github/assets/hypersolutions.jpg" height="47" width="149"></a>

TLS fingerprinting alone isn't enough for modern bot protection. **[Hyper Solutions](https://hypersolutions.co?utm_source=github&utm_medium=readme&utm_campaign=azure-tls)** provides the missing piece - API endpoints that generate valid antibot tokens for:

**Akamai** • **DataDome** • **Kasada** • **Incapsula**

No browser automation. Just simple API calls that return the exact cookies and headers these systems require.

🚀 **[Get Your API Key](https://hypersolutions.co?utm_source=github&utm_medium=readme&utm_campaign=azure-tls)** | 📖 **[Docs](https://docs.hypersolutions.co/)** | 💬 **[Discord](https://discord.gg/akamai)**


azuretls-client

Full-featured plugin-driven HTTP client library

# gentleman [![GitHub release](https://img.shields.io/badge/version-2.0.5-orange.svg?style=flat)](https://github.com/h2non/gentleman/releases) [![GoDoc](https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg)](https://godoc.org/gopkg.in/h2non/gentleman.v2) [![Coverage Status](https://coveralls.io/repos/github/h2non/gentleman/badge.svg?branch=master)](https://coveralls.io/github/h2non/gentleman?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/h2non/gentleman)](https://goreportcard.com/report/github.com/h2non/gentleman) [![Go Version](https://img.shields.io/badge/go-v2.0+-green.svg?style=flat)](https://github.com/h2non/gentleman)

Full-featured, plugin-driven, middleware-oriented toolkit to easily create rich, versatile and composable HTTP clients in [Go](http://golang.org).

<img src="http://s10.postimg.org/5e31ox1ft/gentleman.png" align="right" height="260" />

gentleman embraces extensibility and composition principles in order to provide a flexible way to easily create featured HTTP client layers based on built-in or third-party plugins that you can register and reuse across HTTP clients.

As an example, you can easily provide retry policy capabilities or dynamic server discovery in your HTTP clients simply attaching the [retry](https://github.com/h2non/gentleman-retry) or [consul](https://github.com/h2non/gentleman-consul) plugins.

Take a look to the [examples](#examples), list of [supported plugins](#plugins), [HTTP entities](#http-entities) or [middleware layer](#middleware) to get started.

For testing purposes, see [baloo](https://github.com/h2non/baloo), an utility library for expressive end-to-end HTTP API testing, built on top of `gentleman` toolkit. For HTTP mocking, see [gentleman-mock](https://github.com/h2non/gentleman-mock), which uses [gock](https://github.com/h2non/gock) under the hood for easy and expressive HTTP client request mocking.

## Versions

- [v2](https://github.com/h2non/gentleman/) - Latest version. Stable. Recommended.
- [v1](https://github.com/h2non/gentleman/tree/v1) - First version. Stable. Actively maintained.

## Features

- Plugin driven architecture.
- Simple, expressive, fluent API.
- Idiomatic built on top of `net/http` package.
- Context-aware hierarchical middleware layer supporting all the HTTP life cycle.
- Built-in multiplexer for easy composition capabilities.
- Easy to extend via plugins/middleware.
- Ability to easily intercept and modify HTTP traffic on-the-fly.
- Convenient helpers and abstractions over Go's HTTP primitives.
- URL template path params.
- Built-in JSON, XML and multipart bodies serialization and parsing.
- Easy to test via HTTP mocking (e.g: [gentleman-mock](https://github.com/h2non/gentleman-mock)).
- Supports data passing across plugins/middleware via its built-in context.
- Fits good while building domain-specific HTTP API clients.
- Easy to hack.
- Dependency free.

## Installation

```bash
go get -u gopkg.in/h2non/gentleman.v2
```

## Requirements

- Go 1.9+

## Plugins

<table>
  <tr>
    <th>Name</th>
    <th>Docs</th>
    <th>Status</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/url">url</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/url">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /</a></td>
    <td>Easily declare URL, base URL and path values in HTTP requests</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/auth">auth</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/auth">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Declare authorization headers in your requests</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/body">body</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/body">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Easily define bodies based on JSON, XML, strings, buffers or streams</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/bodytype">bodytype</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/bodytype">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Define body MIME type by alias</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/cookies">cookies</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/cookies">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Declare and store HTTP cookies easily</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/compression">compression</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/compression">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Helpers to define enable/disable HTTP compression</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/headers">headers</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/headers">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Manage HTTP headers easily</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/multipart">multipart</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/multipart">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Create multipart forms easily. Supports files and text fields</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/proxy">proxy</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/proxy">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Configure HTTP proxy servers</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/query">query</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/query">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Easily manage query params</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/redirect">redirect</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/redirect">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Easily configure a custom redirect policy</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/timeout">timeout</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/timeout">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Easily configure the HTTP timeouts (request, dial, TLS...)</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/transport">transport</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/transport">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Define a custom HTTP transport easily</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman/tree/master/plugins/tls">tls</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2/plugins/tls">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman"><img src="https://travis-ci.org/h2non/gentleman.png" /></a></td>
    <td>Configure the TLS options used by the HTTP transport</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman-retry">retry</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2-retry">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2-retry?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman-retry"><img src="https://travis-ci.org/h2non/gentleman-retry.png" /></a></td>
    <td>Provide retry policy capabilities to your HTTP clients</td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman-mock">mock</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2-mock">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2-mock?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman-mock"><img src="https://travis-ci.org/h2non/gentleman-mock.png" /></a></td>
    <td>Easy HTTP mocking using <a href="https://github.com/h2non/gock">gock</a></td>
  </tr>
  <tr>
    <td><a href="https://github.com/h2non/gentleman-consul">consul</a></td>
    <td>
      <a href="https://godoc.org/gopkg.in/h2non/gentleman.v2-consul">
        <img src="https://godoc.org/gopkg.in/h2non/gentleman.v2-consul?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/h2non/gentleman-consul"><img src="https://travis-ci.org/h2non/gentleman-consul.png" /></a></td>
    <td><a href="https://www.consul.io">Consul</a> based server discovery with configurable retry/backoff policy</td>
  </tr>
</table>

### Community plugins

<table>
  <tr>
    <th>Name</th>
    <th>Docs</th>
    <th>Status</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><a href="https://github.com/izumin5210/gentleman-logger">logger</a></td>
    <td>
      <a href="https://godoc.org/github.com/izumin5210/gentleman-logger">
        <img src="https://godoc.org/github.com/izumin5210/gentleman-logger?status.svg" />
      </a>
    </td>
    <td><a href="https://travis-ci.org/izumin5210/gentleman-logger"><img src="https://travis-ci.org/izumin5210/gentleman-logger.png" /></a></td>
    <td>Easily log requests and responses</td>
  </tr>
</table>

[Send](https://github.com/h2non/gentleman/pull/new/master) a PR to add your plugin to the list.

### Creating plugins

You can create your own plugins for a wide variety of purposes, such as server discovery, custom HTTP tranport, modify any request/response param, intercept traffic, authentication and so on.

Plugins are essentially a set of middleware function handlers for one or multiple HTTP life cycle phases exposing [a concrete interface](https://github.com/h2non/gentleman/blob/755d55eef0bd26ae6b4ee19fe59001db2c46a51b/plugin/plugin.go#L16-L35) consumed by gentleman middleware layer.

For more details about plugins see the [plugin](https://github.com/h2non/gentleman/tree/master/plugin) package and [examples](https://github.com/h2non/gentleman/tree/master/_examples/plugin).

Also you can take a look to a plugin [implementation example](https://github.com/h2non/gentleman/blob/master/_examples/plugin/plugin.go).

## HTTP entities

`gentleman` provides two HTTP high level entities: `Client` and `Request`.

Each of these entities provides a common API and are both middleware capable, giving you the ability to plug in custom components with own logic into any of them.

`gentleman` was designed to provide strong reusability capabilities.
This is mostly achieved via its built-in hierarchical, inheritance-based middleware layer.

The following list describes how inheritance hierarchy works and is used across gentleman's entities.

- `Client` entity can inherit from other `Client` entity.
- `Request` entity can inherit from a `Client` entity.
- `Client` entity is mostly designed for reusability.
- `Client` entity can create multiple `Request` entities who implicitly inherits from `Client` entity itself.
- `Request` entity is designed to have specific HTTP request logic that is not typically reused.
- Both `Client` and `Request` entities are full middleware capable interfaces.
- Both `Client` and  `Request` entities can be cloned in order to produce a copy but side-effects free new entity.

You can see an inheritance usage example [here](https://github.com/h2non/gentleman/blob/master/_examples/inheritance/inheritance.go).

## Middleware

gentleman is completely based on a hierarchical middleware layer based on plugins that executes one or multiple function handlers (aka plugin interface) providing a simple way to plug in intermediate custom logic in your HTTP client.

It supports multiple phases which represents the full HTTP request/response life cycle, giving you the ability to perform actions before and after an HTTP transaction happen, even intercepting and stopping it.

The middleware stack chain is executed in FIFO order designed for single thread model.
Plugins can support goroutines, but plugins implementors should prevent data race issues due to concurrency in multithreading programming.

For more implementation details about the middleware layer, see the [middleware](https://github.com/h2non/gentleman/tree/master/middleware) package and [examples](https://github.com/h2non/gentleman/tree/master/_examples/middleware).

#### Middleware phases

Supported middleware phases triggered by gentleman HTTP dispatcher:

- **request** - Executed before a request is sent over the network.
- **response** - Executed when the client receives the response, even if it failed.
- **error** - Executed in case that an error ocurrs, support both injected or native error.
- **stop** - Executed in case that the request has been manually stopped via middleware (e.g: after interception).
- **intercept** - Executed in case that the request has been intercepted before network dialing.
- **before dial** - Executed before a request is sent over the network.
- **after dial** - Executed after the request dialing was done and the response has been received.

Note that the middleware layer has been designed for easy extensibility, therefore new phases may be added in the future and/or the developer could be able to trigger custom middleware phases if needed.

Feel free to fill an issue to discuss this capabilities in detail.

## API

See [godoc reference](https://godoc.org/gopkg.in/h2non/gentleman.v2) for detailed API documentation.

#### Subpackages

- [plugin](https://github.com/h2non/gentleman/tree/master/plugin) - [godoc](https://godoc.org/gopkg.in/h2non/gentleman.v2/plugin) - Plugin layer for gentleman.
- [mux](https://github.com/h2non/gentleman/tree/master/mux) - [godoc](https://godoc.org/gopkg.in/h2non/gentleman.v2/mux) - HTTP client multiplexer with built-in matchers.
- [middleware](https://github.com/h2non/gentleman/tree/master/middleware) - [godoc](https://godoc.org/gopkg.in/h2non/gentleman.v2/middleware) - Middleware layer used by gentleman.
- [context](https://github.com/h2non/gentleman/tree/master/context) - [godoc](https://godoc.org/gopkg.in/h2non/gentleman.v2/context) - HTTP context implementation for gentleman's middleware.
- [utils](https://github.com/h2non/gentleman/tree/master/utils) - [godoc](https://godoc.org/gopkg.in/h2non/gentleman.v2/utils) - HTTP utilities internally used.

## Examples

See [examples](https://github.com/h2non/gentleman/blob/master/_examples) directory for featured examples.

#### Simple request

```go
package main

import (
  "fmt"

  "gopkg.in/h2non/gentleman.v2"
)

func main() {
  // Create a new client
  cli := gentleman.New()

  // Define base URL
  cli.URL("http://httpbin.org")

  // Create a new request based on the current client
  req := cli.Request()

  // Define the URL path at request level
  req.Path("/headers")

  // Set a new header field
  req.SetHeader("Client", "gentleman")

  // Perform the request
  res, err := req.Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  // Reads the whole body and returns it as string
  fmt.Printf("Body: %s", res.String())
}
```

#### Send JSON body

```go
package main

import (
  "fmt"

  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/plugins/body"
)

func main() {
  // Create a new client
  cli := gentleman.New()

  // Define the Base URL
  cli.URL("http://httpbin.org/post")

  // Create a new request based on the current client
  req := cli.Request()

  // Method to be used
  req.Method("POST")

  // Define the JSON payload via body plugin
  data := map[string]string{"foo": "bar"}
  req.Use(body.JSON(data))

  // Perform the request
  res, err := req.Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}
```

#### Composition via multiplexer

```go
package main

import (
  "fmt"

  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/mux"
  "gopkg.in/h2non/gentleman.v2/plugins/url"
)

func main() {
  // Create a new client
  cli := gentleman.New()

  // Define the server url (must be first)
  cli.Use(url.URL("http://httpbin.org"))

  // Create a new multiplexer based on multiple matchers
  mx := mux.If(mux.Method("GET"), mux.Host("httpbin.org"))

  // Attach a custom plugin on the multiplexer that will be executed if the matchers passes
  mx.Use(url.Path("/headers"))

  // Attach the multiplexer on the main client
  cli.Use(mx)

  // Perform the request
  res, err := cli.Request().Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}
```

## License

MIT - Tomas Aparicio


gentleman


<p align="center">
  <a href="https://github.com/bozd4g/go-http-client">
    <img alt="go-http-client" src="https://raw.githubusercontent.com/bozd4g/go-http-client/master/assets/banner.png" width="500">
  </a>
</p>

<h1 align="center">
  go-http-client
</h1>

<p align="center">
  An enhanced http client for <a href="https://golang.org/">Golang</a>
</p>

<p align="center">
  <a href="https://pkg.go.dev/github.com/bozd4g/go-http-client" target="_blank">Documentation on go.dev 🔗</a>
</p>

<p align="center">
  <a href="https://bozd4g.mit-license.org/"><img src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
  <a href="https://github.com/bozd4g/go-http-client/actions/workflows/build.yml"><img src="https://github.com/bozd4g/go-http-client/actions/workflows/build.yml/badge.svg"></a>
  <a href="https://goreportcard.com/report/github.com/bozd4g/go-http-client"><img src="https://goreportcard.com/badge/github.com/bozd4g/go-http-client"></a>
<a href="https://codecov.io/gh/bozd4g/go-http-client">
<img alt="Coverage" src="https://codecov.io/gh/bozd4g/go-http-client/branch/master/graphs/badge.svg?branch=master">
</a>
<a href="https://github.com/avelino/awesome-go">
<img alt="awesome" src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg">
</a>
</p>

This package provides you a http client package for your http requests. You can send requests quicly with this package. If you want to contribute this package, please fork and [create](https://github.com/bozd4g/go-http-client/pulls) a pull request.

## Installation
```
$ go get -u github.com/bozd4g/go-http-client/
```

## Example Usage
```go
package main

import (
	"context"
	"log"

	gohttpclient "github.com/bozd4g/go-http-client"
)

type Post struct {
	ID    int    `json:"id"`
	Title string `json:"title"`
}

func main() {
	ctx := context.Background()
	client := gohttpclient.New("https://jsonplaceholder.typicode.com")

	response, err := client.Get(ctx, "/posts/1")
	if err != nil {
		log.Fatalf("error: %v", err)
	}

	var post Post
	if err := response.Unmarshal(&post); err != nil {
		log.Fatalf("error: %v", err)
	}

	log.Printf(post.Title) // sunt aut facere repellat provident occaecati...
}
```

## License
Copyright (c) 2020 Furkan Bozdag

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


go-http-client

A library for Multiplexing HTTP requests based on multiple Source IPs

# IPMux
![pipeline](https://github.com/optimus-hft/go-ipmux/actions/workflows/go-ci.yml/badge.svg)
[![codecov](https://codecov.io/gh/optimus-hft/go-ipmux/branch/main/graph/badge.svg)](#)
[![Go Report Card](https://goreportcard.com/badge/github.com/optimus-hft/go-ipmux)](https://goreportcard.com/report/github.com/optimus-hft/go-ipmux)
[![Go Reference](https://pkg.go.dev/badge/github.com/optimus-hft/go-ipmux.svg)](https://pkg.go.dev/github.com/optimus-hft/go-ipmux)

## GoLang Library for Multiplexing HTTP Clients based on Source IP
IPMux is an open-source GoLang library that provides a simple and efficient way to multiplex HTTP clients based on source IP addresses. This library is designed to handle scenarios where you need to make HTTP requests from specific network interfaces based on the source IP.

This library could be useful to bypass rate limit errors which operate on source IPs.

## Features
+ Multiplex HTTP clients based on source IP addresses.
+ Customizable options for creating HTTP clients.
+ Easy-to-use interface for seamless integration.
+ Enabling DNS cache with a refresh interval.


## Getting Started
### Installation
```
go get github.com/optimus-hft/go-ipmux
```

### Usage

```go
package main

import (
	"fmt"
	"io"
	"time"

	"github.com/optimus-hft/go-ipmux"
)

func main() {
	// both ips should be attached to your device for IPMux to operate properly
	ips := []string{"192.168.0.1", "192.168.0.2"}
	ipMux, err := ipmux.New(ips, ipmux.WithTimeout(10*time.Second))
	if err != nil {
		fmt.Println(err)
		return
	}

	client := ipMux.Client()
	response, err := client.Get("https://google.com")
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	fmt.Println(io.ReadAll(response.Body))
}

```

## API Documentation
### `func New(ips []string, options ...Option) (*IPMux, error)`
+ ips: List of IP addresses to create HTTP clients for.
+ options: Optional parameters to customize client creation.
Returns a new IPMux instance.

### `func (i *IPMux) Client() *http.Client`
Returns an HTTP client associated with one of the IPs provided in the New function. Returns `http.DefaultClient` if no clients are available.

### `func (i *IPMux) Clients() []*http.Client`
Returns a list of all clients created for the list of IPs given in `New`. Returns a list containing one client (`http.DefaultClient`) when there are no available clients.

### Options
### `WithBaseClient(baseClient *http.Client) Option`
Change the base client used to create clients for IPMux.

### `WithTimeout(timeout time.Duration) Option`
Set timeout on both client and dialer of the clients.

### `WithKeepAlive(keepalive time.Duration) Option`
Set keepalive on dialer of the clients.

### `WithBaseTransport(transport *http.Transport) Option`
Change the base transport (http.RoundTripper) used to create clients for IPMux.

### `WithDialer(dialer *net.Dialer) Option`
Change the base dialer used to create clients for IPMux.

### `WithDNSCache(refreshInterval time.Duration) Option`
Enable the DNS cache feature with a refresh interval.

### `WithContext(ctx context.Context) Option`
Change the default context to control background goroutine like DNS cache refresh. The default context is `context.Background()`.


## Contributing
Pull requests and bug reports are welcome. For major changes, please open an issue first to discuss what you would like to change.

## License
This project is licensed under the MIT License.


go-ipmux

Go http.RoundTripper that emits open telemetry metrics for HTTP requests

# go-otelroundtripper

[![Build](https://github.com/NdoleStudio/go-otelroundtripper/actions/workflows/main.yml/badge.svg)](https://github.com/NdoleStudio/go-otelroundtripper/actions/workflows/main.yml)
[![codecov](https://codecov.io/gh/NdoleStudio/go-otelroundtripper/branch/main/graph/badge.svg)](https://codecov.io/gh/NdoleStudio/go-otelroundtripper)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/NdoleStudio/go-otelroundtripper/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/NdoleStudio/go-otelroundtripper/?branch=main)
[![Go Report Card](https://goreportcard.com/badge/github.com/NdoleStudio/go-otelroundtripper)](https://goreportcard.com/report/github.com/NdoleStudio/go-otelroundtripper)
[![GitHub contributors](https://img.shields.io/github/contributors/NdoleStudio/go-otelroundtripper)](https://github.com/NdoleStudio/go-otelroundtripper/graphs/contributors)
[![GitHub license](https://img.shields.io/github/license/NdoleStudio/go-otelroundtripper?color=brightgreen)](https://github.com/NdoleStudio/go-otelroundtripper/blob/master/LICENSE)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/NdoleStudio/go-otelroundtripper)](https://pkg.go.dev/github.com/NdoleStudio/go-otelroundtripper)


This package provides an easy way to collect http related metrics
(e.g Response times, Status Codes, number of in flight requests etc) for your HTTP API Clients.
You can do this by using this round tripper when instantiating the `http.Client{}`.

## Why this package exists

I currently have to integrate with multiple APIs and I needed a simple way to export metrics for those external
API's. Sometimes external API's have their own SDK and the only input is `http.Client`. In this scenario, I can create
an HTTP client with a round tripper automatically exports metrics according to the open telemetry specification.

## Installation

`go-otelroundtripper` is compatible with modern Go releases in module mode, with Go installed:

```bash
go get github.com/NdoleStudio/go-otelroundtripper
```

Alternatively the same can be achieved if you use `import` in a package:

```go
import "github.com/NdoleStudio/go-otelroundtripper"
```

## Usage

This is a sample code that instantiates an HTTP client which sends requests to `https://example.com`.
You can see a runnable [example here](./example_test.go)

```go
client := http.Client{
    Transport: New(
        WithName("example.com"),
        WithMeter(global.MeterProvider()Meter("otel-round-tripper")),
        WithAttributes(
            semconv.ServiceNameKey.String("otel-round-tripper"),
        ),
    ),
}

response, err := client.Get("https://example.com")
```

## Metrics Emitted

The following metrics will be emitted by this package. Note that `*` will be replaced by the prefix passed in `WithName()`.

- `*.no_request` http calls with nil `http.Request`
- `*.errors` http requests which had an error response i.e `err != nil`
- `*.success` http requests which were successfull. Meaning there were no transport errors
- `*.timeouts` http requests which timed out
- `*.cancelled` http requests with cancelled context
- `*.deadline_exceeded` http requests with context dateline exceeded
- `*.total_duration` total time it takes to execute the http request in milliseconds
- `*.in_flight` concurrent http requests
- `*.attempts` http requests attempted
- `*.failures` http requests with  http status code >= 400
- `*.redirects`  http requests with  300 <= http status code < 400

## Testing

You can run the unit tests for this client from the root directory using the command below:

```bash
go test -v
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details


go-otelroundtripper

# go-req

[![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]  [![Go Report Card][report-card-img]][report-card]

[doc-img]: https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square
[doc]: https://pkg.go.dev/github.com/wenerme/go-req?tab=doc
[ci-img]: https://github.com/wenerme/go-req/actions/workflows/ci.yml/badge.svg
[ci]: https://github.com/wenerme/go-req/actions/workflows/ci.yml
[cov-img]: https://codecov.io/gh/wenerme/go-req/branch/main/graph/badge.svg
[cov]: https://codecov.io/gh/wenerme/go-req/branch/main
[report-card-img]: https://goreportcard.com/badge/github.com/wenerme/go-req
[report-card]: https://goreportcard.com/report/github.com/wenerme/go-req

Declarative golang HTTP client

```go
package req_test

import (
    "fmt"
    "github.com/wenerme/go-req"
    "net/http"
)

func ExampleRequest() {
    // reusable client
    client := req.Request{
        BaseURL: "https://httpbin.org",
        Options: []interface{}{req.JSONEncode, req.JSONDecode},
    }
  
    // dump request and response with body
    client = client.WithHook(req.DebugHook(&req.DebugOptions{Body: true}))
    
    // send request with declarative override
    var out PostResponse
    var r *http.Response
    err := client.With(req.Request{
        Method: http.MethodPost,
        URL: "/post",
        Body: HelloRequest{
          Name: "go-req",
        },
    }).Fetch(&out,&r)
    if err != nil {
      panic(err)
    }
    // print go-req
    fmt.Println(out.JSON.Name)
    // print 200
    fmt.Println(r.StatusCode)
}

type HelloRequest struct {
  Name string
}
type HelloResponse struct {
  Name string
}
type PostResponse struct {
  JSON HelloResponse `json:"json"`
}
```

## Used by

- [wenerme/go-wecom](https://github.com/wenerme/go-wecom)
  - Wechat Work/Wecom/企业微信 Golang SDK


go-req

A Powerful, Lightweight, Easy Http Client, inspired by Web Fetch API

# Fetch - HTTP Client

`HTTP Client` for Go, inspired by the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), and [Axios](https://github.com/axios/axios) + [Got](https://github.com/sindresorhus/got) (Sindre Sorhus).

[![PkgGoDev](https://pkg.go.dev/badge/github.com/go-zoox/fetch)](https://pkg.go.dev/github.com/go-zoox/fetch)
[![Build Status](https://github.com/go-zoox/fetch/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/go-zoox/fetch/actions/workflows/ci.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/go-zoox/fetch)](https://goreportcard.com/report/github.com/go-zoox/fetch)
[![Coverage Status](https://coveralls.io/repos/github/go-zoox/fetch/badge.svg?branch=master)](https://coveralls.io/github/go-zoox/fetch?branch=master)
[![GitHub issues](https://img.shields.io/github/issues/go-zoox/fetch.svg)](https://github.com/go-zoox/fetch/issues)
[![Release](https://img.shields.io/github/tag/go-zoox/fetch.svg?label=Release)](https://github.com/go-zoox/fetch/releases)

## Features

### Main API

- [x] Make HTTP requests
- [x] Easy JSON Response
- [x] GZip support
  - [x] Decode GZip response
  - [x] Encode GZip request (Upload File with GZip)
- [x] HTTP/2 support
- [x] TLS
  - [x] Custom TLS Ca Certificate (Self signed certificate) [Example](https://github.com/go-zoox/examples/tree/master/https/fetch)
  - [x] Custom Client Cert and Key for two-way authentication (Client Cert and Key)
- [x] Simple Auth Methods
  - [x] Basic Auth
  - [x] Bearer Auth
- [x] Support cancel (using context)

### Timeouts and retries

- [x] Support timeout
- [x] Support retry on failure

### Progress

- [x] Support progress and progress events

### File upload and download

- [x] Download files easily
- [x] Upload files easily

### Cache, Proxy and UNIX sockets

- [ ] [RFC compliant caching](https://github.com/sindresorhus/got/blob/main/documentation/cache.md)
- [x] Proxy support
  - [x] Environment variables (HTTP_PROXY/HTTPS_PROXY/SOCKS_PROXY)
  - [x] Custom proxy
- [x] UNIX Domain Sockets
  - [Example: HTTP](https://github.com/go-zoox/examples/tree/master/unix-domain-socket/http)
  - [Example: HTTPs](https://github.com/go-zoox/examples/tree/master/unix-domain-socket/https)

### WebDAV

- [ ] WebDAV protocol support

### Advanced creation

- [ ] Plugin system
- [ ] Middleware system

## Installation

To install the package, run:

```bash
go get github.com/go-zoox/fetch
```

## Methods

- [x] GET
- [x] POST
- [x] PUT
- [x] PATCH
- [x] DELETE
- [x] HEAD
- [ ] OPTIONS
- [ ] TRACE
- [ ] CONNECT

## Getting Started

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
  response, _ := fetch.Get("https://httpbin.zcorky.com/get")
  url := response.Get("url")
  method := response.Get("method")

  fmt.Println(url, method)
}
```

## Examples

### Get

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
  response, err := fetch.Get("https://httpbin.zcorky.com/get")
  if err != nil {
		panic(err)
	}

  fmt.Println(response.JSON())
}
```

### Post

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
  response, err := fetch.Post("https://httpbin.zcorky.com/post", &fetch.Config{
		Body: map[string]interface{}{
			"foo":     "bar",
			"foo2":    "bar2",
			"number":  1,
			"boolean": true,
			"array": []string{
				"foo3",
				"bar3",
			},
			"nest": map[string]string{
				"foo4": "bar4",
			},
		},
	})
	if err != nil {
		panic(err)
	}

  fmt.Println(response.JSON())
}
```

### Put

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
	response, err := fetch.Put("https://httpbin.zcorky.com/put", &fetch.Config{
		Body: map[string]interface{}{
			"foo":     "bar",
			"foo2":    "bar2",
			"number":  1,
			"boolean": true,
			"array": []string{
				"foo3",
				"bar3",
			},
			"nest": map[string]string{
				"foo4": "bar4",
			},
		},
	})
  if err != nil {
		panic(err)
	}


  fmt.Println(response.JSON())
}
```

### Delete

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
	response, err := fetch.Delete("https://httpbin.zcorky.com/Delete", &fetch.Config{
		Body: map[string]interface{}{
			"foo":     "bar",
			"foo2":    "bar2",
			"number":  1,
			"boolean": true,
			"array": []string{
				"foo3",
				"bar3",
			},
			"nest": map[string]string{
				"foo4": "bar4",
			},
		},
	})
	if err != nil {
		panic(err)
	}

  fmt.Println(response.JSON())
}
```

### Timeout

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
  response, err := fetch.Get("https://httpbin.zcorky.com/get", &fetch.Config{
    Timeout: 5 * time.Second,
  })
  if err != nil {
		panic(err)
	}

  fmt.Println(response.JSON())
}
```

### Proxy

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
  response, err := fetch.Get("https://httpbin.zcorky.com/ip", &fetch.Config{
    Proxy: "http://127.0.0.1:17890",
  })
  if err != nil {
		panic(err)
	}

  fmt.Println(response.JSON())
}
```

### Basic Auth

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
  response, err := fetch.Get("https://httpbin.zcorky.com/ip", &fetch.Config{
    BasicAuth: &fetch.BasicAuth{
      Username: "foo",
      Password: "bar",
    },
  })
  if err != nil {
		panic(err)
	}

  fmt.Println(response.JSON())
}
```

### Download

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
	response, err := fetch.Download("https://httpbin.zcorky.com/image", "/tmp/image.webp")
  if err != nil {
		panic(err)
	}
}
```

### Upload

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
		file, _ := os.Open("go.mod")

	response, err := Upload("https://httpbin.zcorky.com/upload", file)
  if err != nil {
		panic(err)
	}

	fmt.Println(response.JSON())
}
```

### Cancel

```go
package main

import (
  "github.com/go-zoox/fetch"
)

func main() {
	file, _ := os.Open("go.mod")

	ctx, cancel := context.WithCancel(context.Background())

	f := fetch.New()
	f.SetBaseURL("https://httpbin.zcorky.com")
	f.SetURL("/delay/3")
	f.SetContext(ctx)

	go func() {
		_, err := f.Execute()
		fmt.Println(err)
	}()

	cancel()
}
```

## Depencencies

- [gjson](github.com/tidwall/gjson) - Get JSON Whenever You Need, you don't
  define type first。

## Inspired By

- [sindresorhus/got](https://github.com/sindresorhus/got) - 🌐 Human-friendly and powerful HTTP request library for Node.js
- [axios/axios](https://github.com/axios/axios) - Promise based HTTP client for the browser and node.js
- [mozillazg/request](https://github.com/mozillazg/request) - A
  developer-friendly HTTP request library for Gopher
- [monaco-io/request](https://github.com/monaco-io/request) - go request, go http client

## License

GoZoox is released under the [MIT License](./LICENSE).


go-zoox/fetch

Simple and lightweight golang package for http requests. based on powerful net/http

![logo](https://github.com/user-attachments/assets/3bef5ed3-a40b-4634-9de4-a2dd43d57f3d)


**A simple and lightweight HTTP client for Go, inspired by Requests (Python) and Guzzle (PHP).**

Grequests provides a declarative, chainable API to streamline HTTP requests in Go, supporting JSON manipulation, form submissions, cookies, file handling, authentication, and proxy configuration—all while remaining lightweight and dependency-free.

---

## **Features**

- **Lightweight & Efficient**: No third-party dependencies, built directly on `net/http`.
- **Flexible Request Handling**: Supports GET, POST, PUT, DELETE, and other HTTP methods.
- **JSON Parsing**: Convert responses into Go structs or string maps.
- **Header & Cookie Management**: Easily set, retrieve, and persist headers and cookies.
- **File Handling**: Upload and download files seamlessly.
- **Authentication**: Supports Basic, Bearer, and custom token authentication.
- **Proxy Support**: Configure custom proxy servers for HTTP requests.

---

## **Installation**

Install Grequests using Go modules:

```sh
go get github.com/lib4u/grequest
```

Or build from source:

```sh
git clone https://github.com/lib4u/grequest.git
cd grequest
go build -o grequest ./
./grequest --version
```

---

## **Usage**

### **Basic GET Request**

```go
req := app.Get("https://jsonplaceholder.typicode.com/todos/1").Do()
fmt.Println(req.Body().GetStrings())
```

### **Parsing JSON Response**

```go
type Todo struct {
    UserID    int    `json:"userId"`
    ID        int    `json:"id"`
    Title     string `json:"title"`
    Completed bool   `json:"completed"`
}

var todo Todo
req := app.Get("https://jsonplaceholder.typicode.com/todos/1").Do()
err := req.Body().GetWithJsonStruct(&todo)
if err != nil {
    fmt.Println("Error decoding JSON")
}
fmt.Println(todo.Title)
```

### **POST Request with JSON Payload**

```go
data := LoginRequest{
    Username: "example",
    Password: "12345",
}
req := app.Post("https://example.site/login").Body().SetJson(data).Do()
fmt.Println(req.Status().GetCode())
```

### **Downloading a File**

```go
app.Get("https://example.com/image.png").Do().Body().SaveFile()
```

### **Multipart Form Submission**

```go
req := app.Post("https://example.site/form/")
req.Header().Set("Client", "number_1")
form := req.FormData().WithMultipart()
form.AddField("first_name", "John")
form.AddFile("photo", "my_photo.png")
form.Push()
req.Do()
```

### **Set count of maximum redirects and retry request if get 404 or 500 HTTP code**

```go
req := app.Get("https://jsonplaceholder.typicode.com/todos/1").MaxRedirect(1).RetryIf(404, 500).Do()
fmt.Println(req.Body().GetStrings())
```

### **Set your context**

```go
ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
defer cancel()
req := app.Get("https://jsonplaceholder.typicode.com/todos/1").DoWithContext(ctx)
fmt.Println(req.Body().GetStrings())
```

### **Authenticated Requests**

```go
// Basic Authentication
app.Post("https://example.site/secret").Auth().SetBasic("user", "password").Do()

// Bearer Token Authentication
app.Post("https://example.site/secret").Auth().SetBearer("myToken").Do()

// Custom Token Authentication
app.Post("https://example.site/secret").Auth().SetToken("Token", "myToken").Do()

// Custom Header Authentication
app.Post("https://example.site/secret").Auth().SetHeader("JSESSIONID", "12345").Do()
```

### **Cookie Handling**

```go
//Save cookie to file 
//By default this saved in  cookies/example.site/cookies.json
req := app.Post("https://example.site/cookies")
req.Cookie().Save()

// Load saved cookies form cookies/example.site/cookies.json
reqWithCookie := app.Post("https://example.site/cookies")
reqWithCookie.Cookie().Load()
reqWithCookie.Do()

// Clear cookies
reqWithCookie.Cookie().Clear()
```
---

## **Contributing**

1. Fork the repository and clone it locally.
2. Create a new branch (`git checkout -b feature/branch-name`).
3. Make your changes and commit (`git commit -m "Description of changes"`).
4. Push your changes and create a pull request.

---

## **License**

Grequests is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

For more details, visit the [GitHub repository](https://github.com/lib4u/grequest).

---


Grequest

Enriches the default go HTTP client with retry functionality

[![Go Report Card](https://goreportcard.com/badge/github.com/ybbus/httpretry)](https://goreportcard.com/report/github.com/ybbus/httpretry)
[![Go build](https://github.com/ybbus/httpretry/actions/workflows/go.yml/badge.svg)](https://github.com/ybbus/httpretry)
[![Codecov](https://codecov.io/github/ybbus/httpretry/branch/master/graph/badge.svg?token=ARYOQ8R1DT)](https://codecov.io/github/ybbus/httpretry)
[![GoDoc](https://godoc.org/github.com/ybbus/httpretry?status.svg)](https://godoc.org/github.com/ybbus/httpretry)
[![GitHub license](https://img.shields.io/github/license/mashape/apistatus.svg)]()

# httpRetry

Enriches the standard go http client with retry functionality using a wrapper around the Roundtripper interface.

The advantage of this library is that it makes use of the default http.Client.
This means you can provide it to any library that accepts the go standard http.Client.
This in turn gives you the possibility to add resilience to a lot of http based go libraries with just a single line of code.
Of course it can also be used as standalone http client in your own projects.

## Installation

```sh
go get -u github.com/ybbus/httpretry
```

## Quickstart

To get a standard http client with retry functionality:

```golang
client := httpretry.NewDefaultClient()
// use this as usual when working with http.Client
```

This single line of code returns a default http.Client that uses an exponential backoff and sends up to 5 retries if the request was not successful.
Requests will be retried if the error seems to be temporary or the requests returns a status code that may change over time (e.g. GetwayTimeout).

### Modify / customize the Roundtripper (http.Transport)

Since httpretry wraps the actual Roundtripper of the http.Client, you should not try to replace / modify the client.Transport field after creation.

You either configure the http.Client upfront and then "make" it retryable like in this code:

```golang
customHttpClient := &http.Client{}
customHttpClient.Transport = &http.Transport{...}

retryClient := httpretry.NewCustomClient(cumstomHttpClient)
```

or you use one of the available helper functions to gain access to the underlying Roundtripper / http.Transport:

```golang
// replaces the original roundtripper
httpretry.ReplaceOriginalRoundtripper(retryClient, myRoundTripper)

// modifies the embedded http.Transport by providing a function that receives the client.Transport as parameter
httpretry.ModifyOriginalTransport(retryClient, func(t *http.Transport) { t.TLSHandshakeTimeout = 5 * time.Second })

// returns the embedded Roundtripper
httpretry.GetOriginalRoundtripper(retryClient)

// returns the embedded Roundtripper as http.Transport if it is of that type
httpretry.GetOriginalTransport(retryClient)
```

### Customize retry settings

You may provide your own Backoff- and RetryPolicy.

```golang
client := httpretry.NewDefaultClient(
    // retry up to 5 times
    httpretry.WithMaxRetryCount(5),
    // retry on status >= 500, if err != nil, or if response was nil (status == 0)
    httpretry.WithRetryPolicy(func(statusCode int, err error) bool {
      return err != nil || statusCode >= 500 || statusCode == 0
    }),
    // every retry should wait one more second
    httpretry.WithBackoffPolicy(func(attemptNum int) time.Duration {
      return time.Duration(attemptNum+1) * 1 * time.Second
    }),
)
```


httpretry

Go HTTP client calls with retries, backoff, and concurrency

# pester

`pester` wraps Go's standard lib http client to provide several options to increase resiliency in your request. If you experience poor network conditions or requests could experience varied delays, you can now pester the endpoint for data.
- Send out multiple requests and get the first back (only used for GET calls)
- Retry on errors
- Backoff

### Simple Example
Use `pester` where you would use the http client calls. By default, pester will use a concurrency of 1, and retry the endpoint 3 times with the `DefaultBackoff` strategy of waiting 1 second between retries.
```go
/* swap in replacement, just switch
   http.{Get|Post|PostForm|Head|Do} to
   pester.{Get|Post|PostForm|Head|Do}
*/
resp, err := pester.Get("http://sethammons.com")
```

### Backoff Strategy
Provide your own backoff strategy, or use one of the provided built in strategies:
- `DefaultBackoff`: 1 second
- `LinearBackoff`: n seconds where n is the retry number
- `LinearJitterBackoff`: n seconds where n is the retry number, +/- 0-33%
- `ExponentialBackoff`: n seconds where n is 2^(retry number)
- `ExponentialJitterBackoff`: n seconds where n is 2^(retry number), +/- 0-33%

```go
client := pester.New()
client.Backoff = func(retry int) time.Duration {
    // set up something dynamic or use a look up table
    return time.Duration(retry) * time.Minute
}
```

### Complete example
For a complete and working example, see the sample directory.
`pester` allows you to use a constructor to control:
- backoff strategy
- retries
- concurrency
- keeping a log for debugging
```go
package main

import (
    "log"
    "net/http"
    "strings"

    "github.com/sethgrid/pester"
)

func main() {
    log.Println("Starting...")

    { // drop in replacement for http.Get and other client methods
        resp, err := pester.Get("http://example.com")
        if err != nil {
            log.Println("error GETing example.com", err)
        }
        defer resp.Body.Close()
        log.Printf("example.com %s", resp.Status)
    }

    { // control the resiliency
        client := pester.New()
        client.Concurrency = 3
        client.MaxRetries = 5
        client.Backoff = pester.ExponentialBackoff
        client.KeepLog = true

        resp, err := client.Get("http://example.com")
        if err != nil {
            log.Println("error GETing example.com", client.LogString())
        }
        defer resp.Body.Close()
        log.Printf("example.com %s", resp.Status)
    }

    { // use the pester version of http.Client.Do
        req, err := http.NewRequest("POST", "http://example.com", strings.NewReader("data"))
        if err != nil {
            log.Fatal("Unable to create a new http request", err)
        }
        resp, err := pester.Do(req)
        if err != nil {
            log.Println("error POSTing example.com", err)
        }
        defer resp.Body.Close()
        log.Printf("example.com %s", resp.Status)
    }
}

```

### Example Log
`pester` also allows you to control the resiliency and can optionally log the errors.
```go
c := pester.New()
c.KeepLog = true

nonExistantURL := "http://localhost:9000/foo"
_, _ = c.Get(nonExistantURL)

fmt.Println(c.LogString())
/*
Output:

1432402837 Get [GET] http://localhost:9000/foo request-0 retry-0 error: Get http://localhost:9000/foo: dial tcp 127.0.0.1:9000: connection refused
1432402838 Get [GET] http://localhost:9000/foo request-0 retry-1 error: Get http://localhost:9000/foo: dial tcp 127.0.0.1:9000: connection refused
1432402839 Get [GET] http://localhost:9000/foo request-0 retry-2 error: Get http://localhost:9000/foo: dial tcp 127.0.0.1:9000: connection refused
*/
```

### Tests

You can run tests in the root directory with `$ go test`. There is a benchmark-like test available with `$ cd benchmarks; go test`.
You can see `pester` in action with `$ cd sample; go run main.go`.

For watching open file descriptors, you can run `watch "lsof -i -P | grep main"` if you started the app with `go run main.go`.
I did this for watching for FD leaks. My method was to alter `sample/main.go` to only run one case (`pester.Get with set backoff stategy, concurrency and retries increased`)
and adding a sleep after the result came back. This let me verify if FDs were getting left open when they should have closed. If you know a better way, let me know!
I was able to see that FDs are now closing when they should :)

![Are we there yet?](http://butchbellah.com/wp-content/uploads/2012/06/Are-We-There-Yet.jpg)

Are we there yet? Are we there yet? Are we there yet? Are we there yet? ...


pester

Simple HTTP and REST client for Go inspired by Ruby rest-client

<p align="center">
  <img src="https://resty.dev/svg/resty-logo.svg" width="175" alt="Resty Logo">
</p>
<p align="center"><strong>Simple HTTP, REST, and SSE client library for Go</strong></p>

<p align="center" style="margin-top:3rem"><a href="https://github.com/go-resty/resty/actions/workflows/ci.yml?query=branch%3Av3" target="_blank"><img src="https://github.com/go-resty/resty/actions/workflows/ci.yml/badge.svg?branch=v3" alt="Resty Build Status">
</a><a href="https://app.codecov.io/gh/go-resty/resty/tree/v3" target="_blank"><img src="https://codecov.io/gh/go-resty/resty/branch/v3/graph/badge.svg" alt="Resty Code Coverage">
</a><a href="https://goreportcard.com/report/resty.dev/v3" target="_blank"><img src="https://goreportcard.com/badge/resty.dev/v3" alt="Go Report Card">
</a><a href="https://pkg.go.dev/resty.dev/v3" target="_blank"><img src="https://pkg.go.dev/badge/resty.dev/v3" alt="Resty GoDoc">
</a><a href="LICENSE"><img src="https://img.shields.io/github/license/go-resty/resty.svg" alt="License"></a> <a href="https://github.com/avelino/awesome-go" target="_blank"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Go"></a></p>
<p align="center" style="margin-bottom:1rem"><a href="https://app.fossa.com/projects/git%2Bgithub.com%2Fgo-resty%2Fresty?ref=badge_shield&amp;issueType=license" alt="FOSSA Status"><img src="https://app.fossa.com/api/projects/git%2Bgithub.com%2Fgo-resty%2Fresty.svg?type=shield&amp;issueType=license"></a>
<a href="https://app.fossa.com/projects/git%2Bgithub.com%2Fgo-resty%2Fresty?ref=badge_shield&amp;issueType=security" alt="FOSSA Status"><img src="https://app.fossa.com/api/projects/git%2Bgithub.com%2Fgo-resty%2Fresty.svg?type=shield&amp;issueType=security"></a></p>


## Documentation

Go to https://resty.dev and refer to godoc.

## Minimum Go Version

Use `go1.23` and above.

## Support & Donate

* Sponsor via [GitHub](https://github.com/sponsors/jeevatkm)
* Donate via [PayPal](https://www.paypal.com/donate/?cmd=_donations&business=QWMZG74FW4QYC&lc=US&item_name=Resty+Library+for+Go&currency_code=USD)

## Versioning

Resty releases versions according to [Semantic Versioning](http://semver.org)

  * Resty v3 provides Go Vanity URL `resty.dev/v3`.
  * Resty v2 migrated away from `gopkg.in` service, `github.com/go-resty/resty/v2`.
  * Resty fully adapted to `go mod` capabilities since `v1.10.0` release.
  * Resty v1 series was using `gopkg.in` to provide versioning. `gopkg.in/resty.vX` points to appropriate tagged versions; `X` denotes version series number and it's a stable release for production use. For e.g. `gopkg.in/resty.v0`.

## Contribution

I would welcome your contribution!

* If you find any improvement or issue you want to fix, feel free to send a pull request.
* The pull requests must include test cases for feature/fix/enhancement with patch coverage of 100%.
* I have done my best to bring pretty good coverage. I would request contributors to do the same for their contribution.

I always look forward to hearing feedback, appreciation, and real-world usage stories from Resty users on [GitHub Discussions](https://github.com/go-resty/resty/discussions). It means a lot to me.

## Creator

[Jeevanandam M.](https://github.com/jeevatkm) (jeeva@myjeeva.com)


## Contributors

Have a look on [Contributors](https://github.com/go-resty/resty/graphs/contributors) page.

## License Info

Resty released under MIT [LICENSE](LICENSE).

Resty [Documentation](https://github.com/go-resty/docs) and website released under Apache-2.0 [LICENSE](https://github.com/go-resty/docs/blob/main/LICENSE).


resty

A nicer interface for golang stdlib HTTP client

# rq [![Build Status][githubaction-img]][githubaction-url] [![Go Report][goreport-img]][goreport-url] [![codecov][codecov-img]][codecov-url]

A nicer interface for golang stdlib HTTP client

## Documents

-   rq: [here][godoc-url]
-   client: [here][godoc-client-url]
-   jar: [here][godoc-jar-url]

[godoc-img]: https://img.shields.io/badge/godoc-Reference-brightgreen.svg
[godoc-url]: https://godoc.org/github.com/ddo/rq
[godoc-client-url]: https://godoc.org/github.com/ddo/rq/client
[godoc-jar-url]: https://godoc.org/github.com/ddo/rq/client/jar
[githubaction-img]: https://github.com/ddo/rq/workflows/Go/badge.svg
[githubaction-url]: https://github.com/ddo/rq/actions
[goreport-img]: https://goreportcard.com/badge/github.com/ddo/rq
[goreport-url]: https://goreportcard.com/report/github.com/ddo/rq
[codecov-img]: https://codecov.io/gh/ddo/rq/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/ddo/rq

## Why?

Because golang HTTP client is a pain in the a...

## Features

-   Compatible with golang `http` stdlib: `http.Request`, `http.Response` and `http.Cookie`
-   Step by step to build your **request**
-   Better HTTP **client**
-   Better **cookie jar**
-   **Import/export** allow we save/transfer requests in JSON
-   **Default setting**: example default `User-Agent` or `Accept-Language`

## Installation

```sh
go get -u github.com/ddo/rq
```

## Getting started

### Simple

```go
import "net/http"
import "github.com/ddo/rq"

r := rq.Get("https://httpbin.org/get")

// query https://httpbin.org/get?q=1&q=2&q=3&_=123456
r.Qs("q", "1", "2")
r.Qs("q", "3")
r.Qs("_", "123456")

// send with golang default HTTP client
res, err := http.DefaultClient.Do(r.ParseRequest())
defer res.Body.Close()
```

### Custom client

In case you did not know that golang default `http.Client` has **no timeout**.
use **rq/client** which has `180s` timeout by default

```go
import "github.com/ddo/rq"
import "github.com/ddo/rq/client"

r := rq.Post("https://httpbin.org/post")

// query
r.Qs("_", "123456")

// Form
r.Send("data", "data value")
r.Send("extra", "extra value")

// use default rq client
// true to tell #Send to read all the response boby when return
data, res, err := client.Send(r, true)
// no need to close res.Body
// read = false -> you need to call res.Body when done reading
```

### Headers

```go
r := rq.Post("https://httpbin.org/post")

r.Set("Content-Type", "application/json")
r.Set("User-Agent", "ddo/rq")
```

### Raw body

```go
r := rq.Post("https://httpbin.org/post")

r.SendRaw(strings.NewReader("raw data binary or json"))
```

## Client [![Doc][godoc-img]][godoc-client-url]

### Default

```go
// by default timeout = 3min
// no cookie jar
// and stops after 10 consecutive requests (10 redirects)
customClient := client.New(nil)
```

### Custom Options

```go
import "github.com/ddo/rq/client/jar"

cookieJar := jar.New()

// custom timeout = 10s and cookie jar
customClient := client.New(&Option{
    Timeout: time.Second * 10,
    jar: cookieJar,
})
```

### Default settings

```go
// set default User-Agent
defaultRq := rq.Get("")
defaultRq.Set("User-Agent", "github.com/ddo/rq")

customClient := client.New(&Option{
    DefaultRq: defaultRq,
})

// from now all the requests called via this customClient
// gonna have the User-Agent header = "github.com/ddo/rq"
// if User-Agent header in request is not set
```

## Redirect

-   Default `client` stops after 10 consecutive requests
-   Or you can use `client.NoRedirect` to disable redirect

```go
client.New(&Option{
    CheckRedirect: client.NoCheckRedirect,
})
```

## Cookies [![Doc][godoc-img]][godoc-jar-url]

```go
import "github.com/ddo/rq/client/jar"

cookieJar := jar.New()

customClient := client.New(&client.Option{
    Jar: cookieJar,
})

// get all cookies by hostname
cookies, err := cookieJar.Get("httpbin.org")

// get a cookie by hostname and name
cookie, err := cookieJar.GetByName("httpbin.org", "cookiename").

// set cookies
err := cookieJar.Set("httpbin.org", cookies)

// set a cookie
err := cookieJar.SetOne("httpbin.org", cookie)

// clear the cookie jar
err := cookieJar.Clear("httpbin.org")

// delete a cookie by it's name
err := cookieJar.Delete("httpbin.org", "cookiename")
```

## Debug

Set env `DLOG=*` to enable logger to see request activities

## TODO

List here [#1](https://github.com/ddo/rq/issues/1)

Sling is a Go HTTP client library for creating and sending API requests

# Sling
[![GoDoc](https://pkg.go.dev/badge/github.com/dghubble/sling.svg)](https://pkg.go.dev/github.com/dghubble/sling)
[![Workflow](https://github.com/dghubble/sling/actions/workflows/test.yaml/badge.svg)](https://github.com/dghubble/sling/actions/workflows/test.yaml?query=branch%3Amain)
[![Sponsors](https://img.shields.io/github/sponsors/dghubble?logo=github)](https://github.com/sponsors/dghubble)
[![Mastodon](https://img.shields.io/badge/follow-news-6364ff?logo=mastodon)](https://fosstodon.org/@typhoon)

<img align="right" src="https://storage.googleapis.com/dghubble/small-gopher-with-sling.png">

Sling is a Go HTTP client library for creating and sending API requests.

Slings store HTTP Request properties to simplify sending requests and decoding responses. Check [usage](#usage) or the [examples](examples) to learn how to compose a Sling into your API client.

### Features

* Method Setters: Get/Post/Put/Patch/Delete/Head
* Add or Set Request Headers
* Base/Path: Extend a Sling for different endpoints
* Encode structs into URL query parameters
* Encode a form or JSON into the Request Body
* Receive JSON success or failure responses

## Install

```
go get github.com/dghubble/sling
```

## Documentation

Read [GoDoc](https://godoc.org/github.com/dghubble/sling)

## Usage

Use a Sling to set path, method, header, query, or body properties and create an `http.Request`.

```go
type Params struct {
    Count int `url:"count,omitempty"`
}
params := &Params{Count: 5}

req, err := sling.New().Get("https://example.com").QueryStruct(params).Request()
client.Do(req)
```

### Path

Use `Path` to set or extend the URL for created Requests. Extension means the path will be resolved relative to the existing URL.

```go
// creates a GET request to https://example.com/foo/bar
req, err := sling.New().Base("https://example.com/").Path("foo/").Path("bar").Request()
```

Use `Get`, `Post`, `Put`, `Patch`, `Delete`, `Head`, `Options`, `Trace`, or `Connect` which are exactly the same as `Path` except they set the HTTP method too.

```go
req, err := sling.New().Post("http://upload.com/gophers")
```

### Headers

`Add` or `Set` headers for requests created by a Sling.

```go
s := sling.New().Base(baseUrl).Set("User-Agent", "Gophergram API Client")
req, err := s.New().Get("gophergram/list").Request()
```

### Query

#### QueryStruct

Define [url tagged structs](https://godoc.org/github.com/google/go-querystring/query). Use `QueryStruct` to encode a struct as query parameters on requests.

```go
// Github Issue Parameters
type IssueParams struct {
    Filter    string `url:"filter,omitempty"`
    State     string `url:"state,omitempty"`
    Labels    string `url:"labels,omitempty"`
    Sort      string `url:"sort,omitempty"`
    Direction string `url:"direction,omitempty"`
    Since     string `url:"since,omitempty"`
}
```

```go
githubBase := sling.New().Base("https://api.github.com/").Client(httpClient)

path := fmt.Sprintf("repos/%s/%s/issues", owner, repo)
params := &IssueParams{Sort: "updated", State: "open"}
req, err := githubBase.New().Get(path).QueryStruct(params).Request()
```

### Body

#### JSON Body

Define [JSON tagged structs](https://golang.org/pkg/encoding/json/). Use `BodyJSON` to JSON encode a struct as the Body on requests.

```go
type IssueRequest struct {
    Title     string   `json:"title,omitempty"`
    Body      string   `json:"body,omitempty"`
    Assignee  string   `json:"assignee,omitempty"`
    Milestone int      `json:"milestone,omitempty"`
    Labels    []string `json:"labels,omitempty"`
}
```

```go
githubBase := sling.New().Base("https://api.github.com/").Client(httpClient)
path := fmt.Sprintf("repos/%s/%s/issues", owner, repo)

body := &IssueRequest{
    Title: "Test title",
    Body:  "Some issue",
}
req, err := githubBase.New().Post(path).BodyJSON(body).Request()
```

Requests will include an `application/json` Content-Type header.

#### Form Body

Define [url tagged structs](https://godoc.org/github.com/google/go-querystring/query). Use `BodyForm` to form url encode a struct as the Body on requests.

```go
type StatusUpdateParams struct {
    Status             string   `url:"status,omitempty"`
    InReplyToStatusId  int64    `url:"in_reply_to_status_id,omitempty"`
    MediaIds           []int64  `url:"media_ids,omitempty,comma"`
}
```

```go
tweetParams := &StatusUpdateParams{Status: "writing some Go"}
req, err := twitterBase.New().Post(path).BodyForm(tweetParams).Request()
```

Requests will include an `application/x-www-form-urlencoded` Content-Type header.

#### Plain Body

Use `Body` to set a plain `io.Reader` on requests created by a Sling.

```go
body := strings.NewReader("raw body")
req, err := sling.New().Base("https://example.com").Body(body).Request()
```

Set a content type header, if desired (e.g. `Set("Content-Type", "text/plain")`).

### Extend a Sling

Each Sling creates a standard `http.Request` (e.g. with some path and query
params) each time `Request()` is called. You may wish to extend an existing Sling to minimize duplication (e.g. a common client or base url).

Each Sling instance provides a `New()` method which creates an independent copy, so setting properties on the child won't mutate the parent Sling.

```go
const twitterApi = "https://api.twitter.com/1.1/"
base := sling.New().Base(twitterApi).Client(authClient)

// statuses/show.json Sling
tweetShowSling := base.New().Get("statuses/show.json").QueryStruct(params)
req, err := tweetShowSling.Request()

// statuses/update.json Sling
tweetPostSling := base.New().Post("statuses/update.json").BodyForm(params)
req, err := tweetPostSling.Request()
```

Without the calls to `base.New()`, `tweetShowSling` and `tweetPostSling` would reference the base Sling and POST to
"https://api.twitter.com/1.1/statuses/show.json/statuses/update.json", which
is undesired.

Recap: If you wish to *extend* a Sling, create a new child copy with `New()`.

### Sending

#### Receive

Define a JSON struct to decode a type from 2XX success responses. Use `ReceiveSuccess(successV interface{})` to send a new Request and decode the response body into `successV` if it succeeds.

```go
// Github Issue (abbreviated)
type Issue struct {
    Title  string `json:"title"`
    Body   string `json:"body"`
}
```

```go
issues := new([]Issue)
resp, err := githubBase.New().Get(path).QueryStruct(params).ReceiveSuccess(issues)
fmt.Println(issues, resp, err)
```

Most APIs return failure responses with JSON error details. To decode these, define success and failure JSON structs. Use `Receive(successV, failureV interface{})` to send a new Request that will automatically decode the response into the `successV` for 2XX responses or into `failureV` for non-2XX responses.

```go
type GithubError struct {
    Message string `json:"message"`
    Errors  []struct {
        Resource string `json:"resource"`
        Field    string `json:"field"`
        Code     string `json:"code"`
    } `json:"errors"`
    DocumentationURL string `json:"documentation_url"`
}
```

```go
issues := new([]Issue)
githubError := new(GithubError)
resp, err := githubBase.New().Get(path).QueryStruct(params).Receive(issues, githubError)
fmt.Println(issues, githubError, resp, err)
```

Pass a nil `successV` or `failureV` argument to skip JSON decoding into that value.

### Modify a Request

Sling provides the raw http.Request so modifications can be made using standard net/http features. For example, in Go 1.7+ , add HTTP tracing to a request with a context:

```go
req, err := sling.New().Get("https://example.com").QueryStruct(params).Request()
// handle error

trace := &httptrace.ClientTrace{
   DNSDone: func(dnsInfo httptrace.DNSDoneInfo) {
      fmt.Printf("DNS Info: %+v\n", dnsInfo)
   },
   GotConn: func(connInfo httptrace.GotConnInfo) {
      fmt.Printf("Got Conn: %+v\n", connInfo)
   },
}

req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))
client.Do(req)
```

### Build an API

APIs typically define an endpoint (also called a service) for each type of resource. For example, here is a tiny Github IssueService which [lists](https://developer.github.com/v3/issues/#list-issues-for-a-repository) repository issues.

```go
const baseURL = "https://api.github.com/"

type IssueService struct {
    sling *sling.Sling
}

func NewIssueService(httpClient *http.Client) *IssueService {
    return &IssueService{
        sling: sling.New().Client(httpClient).Base(baseURL),
    }
}

func (s *IssueService) ListByRepo(owner, repo string, params *IssueListParams) ([]Issue, *http.Response, error) {
    issues := new([]Issue)
    githubError := new(GithubError)
    path := fmt.Sprintf("repos/%s/%s/issues", owner, repo)
    resp, err := s.sling.New().Get(path).QueryStruct(params).Receive(issues, githubError)
    if err == nil {
        err = githubError
    }
    return *issues, resp, err
}
```

## Example APIs using Sling

* Digits [dghubble/go-digits](https://github.com/dghubble/go-digits)
* GoSquared [drinkin/go-gosquared](https://github.com/drinkin/go-gosquared)
* Kala [ajvb/kala](https://github.com/ajvb/kala)
* Parse [fergstar/go-parse](https://github.com/fergstar/go-parse)
* Swagger Generator [swagger-api/swagger-codegen](https://github.com/swagger-api/swagger-codegen)
* Twitter [dghubble/go-twitter](https://github.com/dghubble/go-twitter)
* Stacksmith [jesustinoco/go-smith](https://github.com/jesustinoco/go-smith)
* Spotify [omegastreamtv/Spotify](https://github.com/omegastreamtv/Spotify)

Create a Pull Request to add a link to your own API.

## Motivation

Many client libraries follow the lead of [google/go-github](https://github.com/google/go-github) (our inspiration!), but do so by reimplementing logic common to all clients.

This project borrows and abstracts those ideas into a Sling, an agnostic component any API client can use for creating and sending requests.

## Contributing

See the [Contributing Guide](https://gist.github.com/dghubble/be682c123727f70bcfe7).

## License

[MIT License](LICENSE)


sling

net/http.Client like HTTP Client with options to select specific client TLS Fingerprints to use for requests

# TLS-Client

### Preface

This TLS Client is built upon https://github.com/Carcraftz/fhttp and https://github.com/Carcraftz/utls (https://github.com/refraction-networking/utls). Big thanks to
all contributors so far. Sadly it seems that the original repositories from Carcraftz are not maintained anymore.

### What is TLS Fingerprinting?

Some people think it is enough to change the user-agent header of a request to let the server think that the client
requesting a resource is a specific browser.
Nowadays this is not enough, because the server might use a technique to detect the client browser which is called TLS
Fingerprinting.

Even though this article is about TLS Fingerprinting in NodeJS it well describes the technique in general.
https://httptoolkit.tech/blog/tls-fingerprinting-node-js/#how-does-tls-fingerprinting-work

### Why is this library needed?

With this library you are able to create a http client implementing an interface which is similar to golangs net/http
client interface.
This TLS Client allows you to specify the Client (Browser and Version) you want to use, when requesting a server.

### Features

- ✅ **HTTP/1.1, HTTP/2, HTTP/3** - Full protocol support with automatic negotiation
- ✅ **Protocol Racing** - Chrome-like "Happy Eyeballs" for HTTP/2 vs HTTP/3
- ✅ **TLS Fingerprinting** - Mimic Chrome, Firefox, Safari, and other browsers
- ✅ **HTTP/3 Fingerprinting** - Accurate QUIC/HTTP/3 fingerprints matching real browsers
- ✅ **WebSocket Support** - Maintain TLS fingerprinting over WebSocket connections
- ✅ **Custom Header Ordering** - Control the order of HTTP headers
- ✅ **Proxy Support** - HTTP and SOCKS5 proxies
- ✅ **Cookie Jar Management** - Built-in cookie handling
- ✅ **Certificate Pinning** - Enhanced security with custom certificate validation
- ✅ **Bandwidth Tracking** - Monitor upload/download bandwidth
- ✅ **Language Bindings** - Use from JavaScript (Node.js), Python, and C# via FFI

### Interface

The HTTP Client interface extends the base net/http Client with additional functionality:

```go
type HttpClient interface {
    GetCookies(u *url.URL) []*http.Cookie
    SetCookies(u *url.URL, cookies []*http.Cookie)
    SetCookieJar(jar http.CookieJar)
    GetCookieJar() http.CookieJar
    SetProxy(proxyUrl string) error
    GetProxy() string
    SetFollowRedirect(followRedirect bool)
    GetFollowRedirect() bool
    CloseIdleConnections()
    Do(req *http.Request) (*http.Response, error)
    Get(url string) (resp *http.Response, err error)
    Head(url string) (resp *http.Response, err error)
    Post(url, contentType string, body io.Reader) (resp *http.Response, err error)

    GetBandwidthTracker() bandwidth.BandwidthTracker
    GetDialer() proxy.ContextDialer
    GetTLSDialer() TLSDialerFunc
}
```

### Detailed Documentation

https://bogdanfinn.gitbook.io/open-source-oasis/

### Quick Usage Example

```go
package main

import (
	"fmt"
	"io"
	"log"

	http "github.com/bogdanfinn/fhttp"
	tls_client "github.com/bogdanfinn/tls-client"
	"github.com/bogdanfinn/tls-client/profiles"
)

func main() {
	jar := tls_client.NewCookieJar()
	options := []tls_client.HttpClientOption{
		tls_client.WithTimeoutSeconds(30),
		tls_client.WithClientProfile(profiles.Chrome_144),
		tls_client.WithNotFollowRedirects(),
		tls_client.WithCookieJar(jar), // create cookieJar instance and pass it as argument
	}

	client, err := tls_client.NewHttpClient(tls_client.NewNoopLogger(), options...)
	if err != nil {
		log.Println(err)
		return
	}

	req, err := http.NewRequest(http.MethodGet, "https://tls.peet.ws/api/all", nil)
	if err != nil {
		log.Println(err)
		return
	}

	req.Header = http.Header{
		"accept":                    {"*/*"},
		"accept-language":           {"de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7"},
		"user-agent":                {"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"},
		http.HeaderOrderKey: {
			"accept",
			"accept-language",
			"user-agent",
		},
	}

	resp, err := client.Do(req)
	if err != nil {
		log.Println(err)
		return
	}

	defer resp.Body.Close()

	log.Println(fmt.Sprintf("status code: %d", resp.StatusCode))

	readBytes, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Println(err)
		return
	}

	log.Println(string(readBytes))
}
```

### Questions?

Join my discord support server for free: https://discord.gg/7Ej9eJvHqk
No Support in DMs!


### Appreciate my work?

[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/CaptainBarnius)

---

## 🛡️ Need Antibot Bypass?

<a href="https://hypersolutions.co/?utm_source=github&utm_medium=readme&utm_campaign=tls-client" target="_blank"><img src="https://raw.githubusercontent.com/bogdanfinn/tls-client/master/.github/assets/hypersolutions.jpg" height="47" width="149"></a>

TLS fingerprinting alone isn't enough for modern bot protection. **[Hyper Solutions](https://hypersolutions.co?utm_source=github&utm_medium=readme&utm_campaign=tls-client)** provides the missing piece - API endpoints that generate valid antibot tokens for:

**Akamai** • **DataDome** • **Kasada** • **Incapsula**

No browser automation. Just simple API calls that return the exact cookies and headers these systems require.

🚀 **[Get Your API Key](https://hypersolutions.co?utm_source=github&utm_medium=readme&utm_campaign=tls-client)** | 📖 **[Docs](https://docs.justhyped.dev)** | 💬 **[Discord](https://discord.gg/akamai)**

---

### Powered by
[![JetBrains logo.](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSource)

tls-client

HTTP requests for Gophers. Uses context.Context and doesn't hide the underlying net/http.Client, making it compatible with standard Go APIs. Also includes testing tools

# Requests [![GoDoc](https://godoc.org/github.com/carlmjohnson/requests?status.svg)](https://godoc.org/github.com/carlmjohnson/requests) [![Go Report Card](https://goreportcard.com/badge/github.com/carlmjohnson/requests)](https://goreportcard.com/report/github.com/carlmjohnson/requests) [![Coverage Status](https://coveralls.io/repos/github/earthboundkid/requests/badge.svg)](https://coveralls.io/github/earthboundkid/requests) [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

![Requests logo](https://github.com/earthboundkid/requests/assets/222245/e59a9f82-c6c7-46d8-96b2-ce2f7dd58dce)

## _HTTP requests for Gophers._

**The problem**: Go's net/http is powerful and versatile, but using it correctly for client requests can be extremely verbose.

**The solution**: The requests.Builder type is a convenient way to build, send, and handle HTTP requests. Builder has a fluent API with methods returning a pointer to the same struct, which allows for declaratively describing a request by method chaining.

Requests also comes with tools for building custom http transports, include a request recorder and replayer for testing.

*[See this note on the canonical project URL.](https://gist.github.com/earthboundkid/8915002ae0e531cecdfc58bc6453ac80)*

## Features

- Simplifies HTTP client usage compared to net/http
- Can't forget to close response body
- Checks status codes by default
- Supports context.Context
- JSON serialization and deserialization helpers
- Easily manipulate URLs and query parameters
- Request recording and replaying for tests
- Customizable transports and validators that are compatible with the standard library and third party libraries
- No third party dependencies
- Good test coverage

## Examples
### Simple GET into a string

<table>
<thead>
<tr>
<th><strong>code with net/http</strong></th>
<th><strong>code with requests</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td>

```go
req, err := http.NewRequestWithContext(ctx,
	http.MethodGet, "http://example.com", nil)
if err != nil {
	// ...
}
res, err := http.DefaultClient.Do(req)
if err != nil {
	// ...
}
defer res.Body.Close()
b, err := io.ReadAll(res.Body)
if err != nil {
	// ...
}
s := string(b)
```
</td>
<td>

```go
var s string
err := requests.
	URL("http://example.com").
	ToString(&s).
	Fetch(ctx)
```

</td>
</tr>
<tr><td>11+ lines</td><td>5 lines</td></tr>
</tbody>
</table>


### POST a raw body

<table>
<thead>
<tr>
<th><strong>code with net/http</strong></th>
<th><strong>code with requests</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td>

```go
body := bytes.NewReader(([]byte(`hello, world`))
req, err := http.NewRequestWithContext(ctx, http.MethodPost,
	"https://postman-echo.com/post", body)
if err != nil {
	// ...
}
req.Header.Set("Content-Type", "text/plain")
res, err := http.DefaultClient.Do(req)
if err != nil {
	// ...
}
defer res.Body.Close()
_, err := io.ReadAll(res.Body)
if err != nil {
	// ...
}
```

</td>
<td>

```go
err := requests.
	URL("https://postman-echo.com/post").
	BodyBytes([]byte(`hello, world`)).
	ContentType("text/plain").
	Fetch(ctx)
```

</td>
</tr>
<tr><td>12+ lines</td><td>5 lines</td></tr></tbody></table>

### GET a JSON object

<table>
<thead>
<tr>
<th><strong>code with net/http</strong></th>
<th><strong>code with requests</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td>

```go
var post placeholder
u, err := url.Parse("https://jsonplaceholder.typicode.com")
if err != nil {
	// ...
}
u.Path = fmt.Sprintf("/posts/%d", 1)
req, err := http.NewRequestWithContext(ctx,
	http.MethodGet, u.String(), nil)
if err != nil {
	// ...
}
res, err := http.DefaultClient.Do(req)
if err != nil {
	// ...
}
defer res.Body.Close()
b, err := io.ReadAll(res.Body)
if err != nil {
	// ...
}
err := json.Unmarshal(b, &post)
if err != nil {
	// ...
}
```
</td><td>

```go
var post placeholder
err := requests.
	URL("https://jsonplaceholder.typicode.com").
	Pathf("/posts/%d", 1).
	ToJSON(&post).
	Fetch(ctx)
```

</td>
</tr>
<tr><td>18+ lines</td><td>7 lines</td></tr></tbody></table>

### POST a JSON object and parse the response

```go
var res placeholder
req := placeholder{
	Title:  "foo",
	Body:   "baz",
	UserID: 1,
}
err := requests.
	URL("/posts").
	Host("jsonplaceholder.typicode.com").
	BodyJSON(&req).
	ToJSON(&res).
	Fetch(ctx)
// net/http equivalent left as an exercise for the reader
```

### Set custom headers for a request

```go
// Set headers
var headers postman
err := requests.
	URL("https://postman-echo.com/get").
	UserAgent("bond/james-bond").
	ContentType("secret").
	Header("martini", "shaken").
	Fetch(ctx)
```

### Easily manipulate URLs and query parameters

```go
u, err := requests.
	URL("https://prod.example.com/get?a=1&b=2").
	Hostf("%s.example.com", "dev1").
	Param("b", "3").
	ParamInt("c", 4).
	URL()
if err != nil { /* ... */ }
fmt.Println(u.String()) // https://dev1.example.com/get?a=1&b=3&c=4
```

### Record and replay responses

```go
// record a request to the file system
var s1, s2 string
err := requests.URL("http://example.com").
	Transport(reqtest.Record(nil, "somedir")).
	ToString(&s1).
	Fetch(ctx)
check(err)

// now replay the request in tests
err = requests.URL("http://example.com").
	Transport(reqtest.Replay("somedir")).
	ToString(&s2).
	Fetch(ctx)
check(err)
assert(s1 == s2) // true
```

## FAQs

[See wiki](https://github.com/earthboundkid/requests/wiki) for more details.

### Why not just use the standard library HTTP client?

Brad Fitzpatrick, long time maintainer of the net/http package, [wrote an extensive list of problems with the standard library HTTP client](https://github.com/bradfitz/exp-httpclient/blob/master/problems.md). His four main points (ignoring issues that can't be resolved by a wrapper around the standard library) are:

> - Too easy to not call Response.Body.Close.
> - Too easy to not check return status codes
> - Context support is oddly bolted on
> - Proper usage is too many lines of boilerplate

Requests solves these issues by always closing the response body, checking status codes by default, always requiring a `context.Context`, and simplifying the boilerplate with a descriptive UI based on fluent method chaining.

### Why requests and not some other helper library?

There are two major flaws in other libraries as I see it. One is that in other libraries support for `context.Context` tends to be bolted on if it exists at all. Two, many hide the underlying `http.Client` in such a way that it is difficult or impossible to replace or mock out. Beyond that, I believe that none have achieved the same core simplicity that the requests library has.

### How do I just get some JSON?

```go
var data SomeDataType
err := requests.
	URL("https://example.com/my-json").
	ToJSON(&data).
	Fetch(ctx)
```

### How do I post JSON and read the response JSON?

```go
body := MyRequestType{}
var resp MyResponseType
err := requests.
	URL("https://example.com/my-json").
	BodyJSON(&body).
	ToJSON(&resp).
	Fetch(ctx)
```

### How do I just save a file to disk?

It depends on exactly what you need in terms of file atomicity and buffering, but this will work for most cases:

```go
err := requests.
	URL("http://example.com").
	ToFile("myfile.txt").
	Fetch(ctx)
```

For more advanced use case, use `ToWriter`.

### How do I save a response to a string?

```go
var s string
err := requests.
	URL("http://example.com").
	ToString(&s).
	Fetch(ctx)
```

### How do I validate the response status?

By default, if no other validators are added to a builder, requests will check that the response is in the 2XX range. If you add another validator, you can add `builder.CheckStatus(200)` or `builder.AddValidator(requests.DefaultValidator)` to the validation stack.

To disable all response validation, run `builder.AddValidator(nil)`.

## Contributing

Please [create a discussion](https://github.com/earthboundkid/requests/discussions) before submitting a pull request for a new feature.


requests

Advanced HTTP client with HTTP/1.1, HTTP/2, HTTP/3 (QUIC), SOCKS5 proxy support and browser-grade TLS fingerprinting

surf

go-retryablehttp
================

[![Build Status](http://img.shields.io/travis/hashicorp/go-retryablehttp.svg?style=flat-square)][travis]
[![Go Documentation](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)][godocs]

[travis]: http://travis-ci.org/hashicorp/go-retryablehttp
[godocs]: http://godoc.org/github.com/hashicorp/go-retryablehttp

The `retryablehttp` package provides a familiar HTTP client interface with
automatic retries and exponential backoff. It is a thin wrapper over the
standard `net/http` client library and exposes nearly the same public API. This
makes `retryablehttp` very easy to drop into existing programs.

`retryablehttp` performs automatic retries under certain conditions. Mainly, if
an error is returned by the client (connection errors, etc.), or if a 500-range
response code is received (except 501), then a retry is invoked after a wait
period.  Otherwise, the response is returned and left to the caller to
interpret.

The main difference from `net/http` is that requests which take a request body
(POST/PUT et. al) can have the body provided in a number of ways (some more or
less efficient) that allow "rewinding" the request body if the initial request
fails so that the full request can be attempted again. See the
[godoc](http://godoc.org/github.com/hashicorp/go-retryablehttp) for more
details.

Version 0.6.0 and before are compatible with Go prior to 1.12. From 0.6.1 onward, Go 1.12+ is required.
From 0.6.7 onward, Go 1.13+ is required.

Example Use
===========

Using this library should look almost identical to what you would do with
`net/http`. The most simple example of a GET request is shown below:

```go
resp, err := retryablehttp.Get("/foo")
if err != nil {
    panic(err)
}
```

The returned response object is an `*http.Response`, the same thing you would
usually get from `net/http`. Had the request failed one or more times, the above
call would block and retry with exponential backoff.

## Getting a stdlib `*http.Client` with retries

It's possible to convert a `*retryablehttp.Client` directly to a `*http.Client`.
This makes use of retryablehttp broadly applicable with minimal effort. Simply
configure a `*retryablehttp.Client` as you wish, and then call `StandardClient()`:

```go
retryClient := retryablehttp.NewClient()
retryClient.RetryMax = 10

standardClient := retryClient.StandardClient() // *http.Client
```

For more usage and examples see the
[pkg.go.dev](https://pkg.go.dev/github.com/hashicorp/go-retryablehttp).


go-retryablehttp

A Go "clone" of the great and famous Requests library

# GRequests

GRequests provides a clean wrapper around Go's `net/http` package.  It mimics the convenience of the Python Requests library while keeping the power and safety of Go.

[![Join the chat at https://gitter.im/levigross/grequests](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/levigross/grequests?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

## Features

- Simple helpers for every HTTP verb
- Context aware request functions for easy cancellation
- RequestOptions for headers, query parameters, proxies, cookies and more
- Built in support for JSON and XML responses
- File uploads and convenient download helpers
- Session type for reusing cookies between requests

## Installation

```bash
go get github.com/levigross/grequests/v2
```

## Quick start

```go
package main

import (
    "context"
    "log"

    "github.com/levigross/grequests/v2"
)

func main() {
    resp, err := grequests.Get(context.Background(), "https://httpbin.org/get",
        grequests.UserAgent("MyAgent"))
    if err != nil {
        log.Fatal(err)
    }

    var data map[string]any
    if err := resp.JSON(&data); err != nil {
        log.Fatal(err)
    }
    log.Println(data)
}
```

### Uploading a file

```go
fd, _ := grequests.FileUploadFromDisk("testdata/file.txt")
ro := &grequests.RequestOptions{
    Files: fd,
    Data:  map[string]string{"desc": "test"},
}
resp, err := grequests.Post(context.Background(), "https://httpbin.org/post",
    grequests.FromRequestOptions(ro))
```

### Using a session

```go
sess := grequests.NewSession(nil)
_, _ = sess.Get(context.Background(), "https://httpbin.org/cookies/set?one=two", nil)
resp, _ := sess.Get(context.Background(), "https://httpbin.org/cookies", nil)
log.Println(resp.String())
```

See the documentation for a full list of available options.

## License

GRequests is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.


The Best Go Libraries For Networking - HTTP Clients (24)