httpclient

https://pkg.go.dev/github.com/luckytea/httpclient
Admin
A simple Go package providing an HTTP client with fasthttp, retry logic, timeout support, and...
Tokens:3,018
Snippets:32
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Create HTTP Client with Default Parameters

Source: https://pkg.go.dev/github.com/luckytea/httpclient

NewDefault returns a new http client initialized with default retry and timeout settings, and a default backoff strategy.

```go
func NewDefault() Client {
}

```

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

### Create HTTP Client with Custom Retry and Timeout

Source: https://pkg.go.dev/github.com/luckytea/httpclient

New returns a new http client configured with specified retry count and timeout duration, along with a backoff strategy.

```go
func New(retry int, timeout time.Duration) Client {
}

```

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

### NewDefault

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Initializes a new HTTP client with default retry and timeout settings, along with a default backoff configuration.

```APIDOC
## NewDefault

### Description
Returns a new http client with default parameters and backoff strategy.

### Method
func NewDefault() Client
```

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

### Client.Do

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Performs the given HTTP request and fills the provided HTTP response. This is a fundamental method for executing requests.

```APIDOC
## Client.Do

### Description
Performs the given HTTP request and fills the provided HTTP response.

### Method
POST

### Endpoint
/request

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **req** (*fasthttp.Request) - Required - The HTTP request object to be performed.
- **resp** (*fasthttp.Response) - Required - The HTTP response object to be filled with the result.

### Request Example
```json
{
  "req": "fasthttp.Request object",
  "resp": "fasthttp.Response object"
}
```

### Response
#### Success Response (200)
Returns an error if the request fails, otherwise nil.

#### Response Example
```json
{
  "error": null
}
```
```

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

### Do

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Executes an HTTP request using the client's configuration, including retries and timeouts.

```APIDOC
## Do

### Description
Executes an HTTP request with the configured client, handling retries and timeouts.

### Method
func (c *Client) Do(req *fasthttp.Request, resp *fasthttp.Response) error

### Parameters
- **req** (*fasthttp.Request) - The HTTP request object.
- **resp** (*fasthttp.Response) - The HTTP response object to populate.
```

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

### New

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Creates a new HTTP client with specified retry count and timeout duration, utilizing a default backoff strategy.

```APIDOC
## New

### Description
Creates a new http client with given parameters and a default backoff strategy.

### Method
func New(retry int, timeout time.Duration) Client

### Parameters
- **retry** (int) - The maximum number of retry attempts for a request.
- **timeout** (time.Duration) - The timeout duration for each HTTP request.
```

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

### Create HTTP Client with Custom Metric Function

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Use NewWithMetricFunc to create an HTTP client with a custom function for observing request latency. This provides flexibility in how metrics are recorded.

```go
// metric func
var latencyFunc = func(start time.Time, domain string) {
    latencyMetric.WithLabelValues(domain).Observe(float64(time.Since(start).Nanoseconds()) / 1000000)
}

// func
client := httpclient.NewWithMetricFunc("domain", latencyFunc)

// request
if err := p.client.DoTimeout(req, resp); err != nil {
    // error handling
}

```

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

### Perform HTTP Request

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Use the Do method to perform an HTTP request and populate the response. This method is available from v1.1.3.

```go
func (c *Client) Do(req *fasthttp.Request, resp *fasthttp.Response) error
```

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

### NewWithMetricFunc

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Creates a new HTTP client with default configurations, allowing a custom function to handle Prometheus metric reporting for request latency.

```APIDOC
## NewWithMetricFunc

### Description
Returns a new http client with default parameters and backoff strategy, accepting a custom function for reporting latency metrics.

### Method
func NewWithMetricFunc(domain string, latencyFunc func(start time.Time, domain string)) Client

### Parameters
- **domain** (string) - The domain name associated with the request.
- **latencyFunc** (func(start time.Time, domain string)) - A callback function to observe latency metrics.
```

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

### Create HTTP Client with Prometheus Metric

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Use NewWithMetric to create an HTTP client that integrates with Prometheus for tracking request latency. This requires a pre-defined Prometheus HistogramVec metric.

```go
// metric
var netSourcesLatencyHistogram = func() *prometheus.HistogramVec {
    var metric = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Namespace: "service",
            Subsystem: "net",
            Name:      "sources_latency",
            Help:      "Third party response latency histogram.",
            Buckets:   prometheus.ExponentialBuckets(0.05, 2, 8),
        }, []string{"source"})
    prometheus.MustRegister(metric)

    return metric
}()

// create
client := httpclient.NewWithMetric("domain", netSourcesLatencyHistogram)

// request
if err := p.client.DoTimeout(req, resp); err != nil {
    // error handling
}

```

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

### Define HTTP Client Structure

Source: https://pkg.go.dev/github.com/luckytea/httpclient

The Client struct holds configuration for making HTTP requests, including retry count, timeout, backoff strategy, and the underlying fasthttp client.

```go
type Client struct {
	RetryMax int              // Количество попыток запроса.
	Timeout  time.Duration    // Таймаут для http запроса.
	Backoff  *Backoff         // Рассчёт времени ожидания между попытками запроса.
	HTTP     *fasthttp.Client // HTTP клиент.
	// contains filtered or unexported fields
}

```

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

### DoContext

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Performs an HTTP request with context support, allowing for cancellation and deadlines.

```APIDOC
## DoContext

### Description
Executes an HTTP request with context support, enabling cancellation and deadline propagation.

### Method
func (c *Client) DoContext(ctx context.Context, req *fasthttp.Request, resp *fasthttp.Response) error

### Parameters
- **ctx** (context.Context) - The context for the request.
- **req** (*fasthttp.Request) - The HTTP request object.
- **resp** (*fasthttp.Response) - The HTTP response object to populate.
```

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

### Create New Backoff Calculator

Source: https://pkg.go.dev/github.com/luckytea/httpclient

NewBackoff returns a function for calculating new backoff durations based on minimum and maximum time limits.

```go
func NewBackoff(min, max time.Duration) *Backoff {
}

```

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

### Define Default Retry and Timeout Constants

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Constants DefaultRetry and DefaultTimeout define the default number of retries and server response timeout, respectively. These are used when initializing the http client with default parameters.

```go
const (
	// DefaultRetry - количество ретраев под текущую реализацию переключения между основными api и failover.
	DefaultRetry = 2
	// DefaultTimeout - стандартное время ожидания ответа от сервера.
	DefaultTimeout = 3 * time.Second
)

```

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

### NewWithMetric

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Constructs a new HTTP client with default retry and timeout settings, integrated with Prometheus metrics for monitoring request latency.

```APIDOC
## NewWithMetric

### Description
Returns a new http client with default parameters and backoff strategy, including Prometheus metric integration for tracking request latency.

### Method
func NewWithMetric(domain string, latencyMetric *prometheus.HistogramVec) Client

### Parameters
- **domain** (string) - The domain name for which metrics are being collected.
- **latencyMetric** (*prometheus.HistogramVec) - A Prometheus HistogramVec to record latency metrics.
```

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

### Perform HTTP Request with Context

Source: https://pkg.go.dev/github.com/luckytea/httpclient

The DoContext method performs an HTTP request, respecting the provided context's deadline or timeout. This method was added in v1.2.0.

```go
func (c *Client) DoContext(ctx context.Context, req *fasthttp.Request, resp *fasthttp.Response) error
```

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

### Perform HTTP Request with Timeout

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Use DoTimeout to execute an HTTP request and wait for a response within a specified duration. This method is suitable for requests with a fixed timeout.

```go
func (c *Client) DoTimeout(req *fasthttp.Request, resp *fasthttp.Response) error
```

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

### Set Client Timeout

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Configure the default timeout for all subsequent requests made by the client using SetTimeout. This method was introduced in v1.1.3.

```go
func (c *Client) SetTimeout(timeout time.Duration)
```

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

### Check HTTP Request Retry Status with Backoff

Source: https://pkg.go.dev/github.com/luckytea/httpclient

CheckRetryWithBackoff determines if another attempt should be made, incorporating backoff delays between retries if necessary.

```go
func (c *Client) CheckRetryWithBackoff(try int) bool {
}

```

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

### Client.DoContext

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Performs the given request with context deadline or waits for response during the given timeout duration. This method allows for request cancellation and deadline enforcement.

```APIDOC
## Client.DoContext

### Description
Performs the given request with context deadline or waits for response during the given timeout duration.

### Method
POST

### Endpoint
/request/context

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **ctx** (context.Context) - Required - The context for the request, used for cancellation and deadlines.
- **req** (*fasthttp.Request) - Required - The HTTP request object.
- **resp** (*fasthttp.Response) - Required - The HTTP response object to be filled.

### Request Example
```json
{
  "ctx": "context.Context object",
  "req": "fasthttp.Request object",
  "resp": "fasthttp.Response object"
}
```

### Response
#### Success Response (200)
Returns an error if the request fails, otherwise nil.

#### Response Example
```json
{
  "error": null
}
```
```

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

### DoTimeout

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Executes an HTTP request with a specific timeout, overriding the client's default timeout if necessary.

```APIDOC
## DoTimeout

### Description
Executes an HTTP request with a specific timeout. This method respects the client's configured timeout.

### Method
func (c *Client) DoTimeout(req *fasthttp.Request, resp *fasthttp.Response) error

### Parameters
- **req** (*fasthttp.Request) - The HTTP request object.
- **resp** (*fasthttp.Response) - The HTTP response object to populate.
```

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

### Define Backoff Structure

Source: https://pkg.go.dev/github.com/luckytea/httpclient

The Backoff struct defines parameters for exponential backoff, including minimum and maximum durations, and a custom calculation function.

```go
type Backoff struct {
	Min       time.Duration
	Max       time.Duration
	Calculate func(int) time.Duration
}

```

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

### Client.DoTimeout

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Performs the given request and waits for response during the given timeout duration. This method is useful for setting a specific time limit for a request.

```APIDOC
## Client.DoTimeout

### Description
Performs the given request and waits for response during the given timeout duration.

### Method
POST

### Endpoint
/request/timeout

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **req** (*fasthttp.Request) - Required - The HTTP request object.
- **resp** (*fasthttp.Response) - Required - The HTTP response object to be filled.

### Request Example
```json
{
  "req": "fasthttp.Request object",
  "resp": "fasthttp.Response object"
}
```

### Response
#### Success Response (200)
Returns an error if the request fails, otherwise nil.

#### Response Example
```json
{
  "error": null
}
```
```

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

### CheckRetryWithBackoff

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Evaluates whether to retry a request, incorporating backoff logic for waiting periods between retries.

```APIDOC
## CheckRetryWithBackoff

### Description
Determines if a retry attempt should be made, considering backoff strategy. If retries are exhausted, it returns immediately; otherwise, it waits according to the backoff function before returning.

### Method
func (c *Client) CheckRetryWithBackoff(try int) bool

### Parameters
- **try** (int) - The current attempt number.
```

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

### Client.SetTimeout

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Sets the timeout duration for subsequent requests made by the client. This affects the default timeout for operations.

```APIDOC
## Client.SetTimeout

### Description
Sets the timeout duration for subsequent requests made by the client.

### Method
PUT

### Endpoint
/client/timeout

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **timeout** (time.Duration) - Required - The duration to set as the timeout for requests.

### Request Example
```json
{
  "timeout": "10s"
}
```

### Response
#### Success Response (200)
No explicit response body, indicates success.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### SetTimeout

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Updates the timeout duration for all subsequent HTTP requests made by this client.

```APIDOC
## SetTimeout

### Description
Sets the timeout duration for all subsequent HTTP requests made by this client.

### Method
func (c *Client) SetTimeout(timeout time.Duration)

### Parameters
- **timeout** (time.Duration) - The new timeout duration for requests.
```

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

### Check HTTP Request Retry Status

Source: https://pkg.go.dev/github.com/luckytea/httpclient

CheckRetry determines if another attempt should be made for an HTTP request based on the current try count.

```go
func (c *Client) CheckRetry(try int) bool {
}

```

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

### CheckRetry

Source: https://pkg.go.dev/github.com/luckytea/httpclient

Determines if a retry attempt should be made based on the current try count.

```APIDOC
## CheckRetry

### Description
Checks if a retry attempt should be made based on the current number of tries.

### Method
func (c *Client) CheckRetry(try int) bool

### Parameters
- **try** (int) - The current attempt number.
```
Tokens:
Raw