README
¶
httpx
A an extended http package for go
Documentation
¶
Overview ¶
Example ¶
package main
import (
"fmt"
"net/http"
"os"
"time"
"github.com/tflyons/httpx"
)
func NewClient() httpx.Client {
c := httpx.DefaultClient
// set a header to be sent on every request
c = httpx.SetHeader(c, "some-header", "1234")
// limit the total request volume to 100 per minute
c = httpx.SetRateLimit(c, 100, time.Minute)
// limit every request to 30 seconds round trip
c = httpx.SetTimeout(c, time.Second*30)
// set an initializer to load a token from a file into the header prior to doing calls
c = httpx.SetInitializer(c, func(next httpx.Client) (httpx.ClientFunc, error) {
token, err := os.ReadFile("mytoken.txt")
if err != nil {
return nil, err
}
return httpx.SetHeader(next, "SOME-TOKEN", string(token)), nil
})
return c
}
func main() {
c := NewClient()
thing, err := GetThing(c)
if err != nil {
panic(err)
}
fmt.Println(thing)
}
type Thing struct {
Foo string `json:"foo"`
Bar int `json:"bar"`
}
func GetThing(baseClient httpx.Client) (Thing, error) {
c := httpx.SetHeader(baseClient, "ThingSpecificHeader", "abcd")
c = httpx.RequireResponseStatus(c, http.StatusOK)
var thing Thing
c = httpx.SetResponseBodyHandlerJSON(c, &thing)
c = httpx.SetRequest(c, http.MethodGet, "http://example.com/things")
_, err := c.Do(nil)
return thing, err
}
Output:
Index ¶
- Variables
- type Client
- type ClientFunc
- func AddCookies(c Client, cookie ...*http.Cookie) ClientFunc
- func AddHeader(c Client, key string, value ...string) ClientFunc
- func RequireResponseBody(c Client) ClientFunc
- func RequireResponseStatus(c Client, status ...int) ClientFunc
- func SetCookies(c Client, cookie ...*http.Cookie) ClientFunc
- func SetHeader(c Client, key string, value ...string) ClientFunc
- func SetInitializer(c Client, init Initializer) ClientFunc
- func SetRateLimit(c Client, max int, duration time.Duration) ClientFunc
- func SetRequest(c Client, method string, url string) ClientFunc
- func SetRequestBody(c Client, m Marshaller, v any) ClientFunc
- func SetRequestBodyJSON(c Client, v any) ClientFunc
- func SetRequestWithContext(ctx context.Context, c Client, method string, url string) ClientFunc
- func SetResponseBodyHandler(c Client, u Unmarshaller, ptr any) ClientFunc
- func SetResponseBodyHandlerJSON(c Client, ptr any) ClientFunc
- func SetTimeout(c Client, d time.Duration) ClientFunc
- type Initializer
- type Marshaller
- type Unmarshaller
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrBodyClose = fmt.Errorf("body could not be closed")
Functions ¶
This section is empty.
Types ¶
type Client ¶
Client performs an http request and returns a response and error.
When implementing, if the error is not nil, the response may or may not be nil. If the error is nil then the response should not be nil
Example ¶
package main
import (
"log"
"net/http"
"os"
"time"
"github.com/tflyons/httpx"
)
func main() {
c := httpx.DefaultClient
// set a header to be sent on every request
c = httpx.SetHeader(c, "some-header", "1234")
// limit the total request volume to 100 per minute
c = httpx.SetRateLimit(c, 100, time.Minute)
// limit every request to 30 seconds round trip
c = httpx.SetTimeout(c, time.Second*30)
// set an initializer to load a token from a file into the header prior to doing calls
c = httpx.SetInitializer(c, func(next httpx.Client) (httpx.ClientFunc, error) {
token, err := os.ReadFile("mytoken.txt")
if err != nil {
return nil, err
}
return httpx.SetHeader(next, "SOME-TOKEN", string(token)), nil
})
req, err := http.NewRequest(http.MethodGet, "example.com", nil)
if err != nil {
log.Fatal(err)
}
resp, err := c.Do(req)
if err != nil {
log.Fatal(err)
}
log.Println(resp.StatusCode)
}
Output:
var DefaultClient Client = http.DefaultClient
DefaultClient is a simple wrapper around http.DefaultClient
type ClientFunc ¶
ClientFunc is an adapter to allow the use of ordinary functions as HTTP Clients.
If f is a function with the appropriate signature, ClientFunc(f) is a Client that calls f.
func AddCookies ¶
func AddCookies(c Client, cookie ...*http.Cookie) ClientFunc
AddCookie adds a cookie to the request
func AddHeader ¶
func AddHeader(c Client, key string, value ...string) ClientFunc
AddHeader appends a header value on the request before the request is executed
func RequireResponseBody ¶
func RequireResponseBody(c Client) ClientFunc
RequireResponseBody returns a non-nil error if the response body is nil
func RequireResponseStatus ¶
func RequireResponseStatus(c Client, status ...int) ClientFunc
RequireResponseStatus returns a non-nil error if the response status does not match one of the statuses given
func SetCookies ¶
func SetCookies(c Client, cookie ...*http.Cookie) ClientFunc
SetCookies clears any existing cookies on the request and sets the value to the cookies given
if the underlying Client implements a cookie jar those cookies in the jar are not removed
func SetHeader ¶
func SetHeader(c Client, key string, value ...string) ClientFunc
SetHeader sets a header value on the request before the request is executed
func SetInitializer ¶
func SetInitializer(c Client, init Initializer) ClientFunc
SetInitializer is a helper function for constructing clients that may need to initialize with some external dependency. It will retry the init function until it suceeds
func SetRateLimit ¶
func SetRateLimit(c Client, max int, duration time.Duration) ClientFunc
SetRateLimit is a simple rate limited that will enforce a client side request limit within a given duration
For example, if max is set to 100 and duration is set to 1*time.Minute then the client can perform at most 100 requests per minute. All of these requests may occur at any time within that minute.
Duration must be greater than 0 or else the underlying function will panic. Max must be greater than 0 or else the client may deadlock
func SetRequest ¶
func SetRequest(c Client, method string, url string) ClientFunc
SetRequest adds a request to the client to perform when the client calls Do.
This overrides any existing request. Generally it should be the last decoration before calling (Client).Do
func SetRequestBody ¶
func SetRequestBody(c Client, m Marshaller, v any) ClientFunc
SetRequestBody sets the value v to the request body using the given Marshaller
func SetRequestBodyJSON ¶
func SetRequestBodyJSON(c Client, v any) ClientFunc
SetRequestBodyJSON is a helper function around SetHeader and SetRequestBody for json specific encoding
func SetRequestWithContext ¶
SetRequestWithContext adds a request with context to the client to perform when the client calls Do.
This overrides any existing request. Generally it should be the last decoration before calling (Client).Do
func SetResponseBodyHandler ¶
func SetResponseBodyHandler(c Client, u Unmarshaller, ptr any) ClientFunc
SetResponseBodyHandler adds a function to unmarshal the response body into a given pointer ptr
func SetResponseBodyHandlerJSON ¶
func SetResponseBodyHandlerJSON(c Client, ptr any) ClientFunc
SetResponseJSONReader performs the request and attempts to unmarshal the response body as json
func SetTimeout ¶
func SetTimeout(c Client, d time.Duration) ClientFunc
SetTimeout sets a time limit on the entire lifetime of the request including connection and header reads
type Initializer ¶
type Initializer func(Client) (ClientFunc, error)
Initializer is a function signature that accepts a Client and returns either a client function or an error
type Marshaller ¶
Marshaller accepts a single parameter and returns a byte slice and error
type Unmarshaller ¶
Unmarshaller decodes the byte array into the given pointer
Source Files
Directories