README
¶
haruhi
Welcome! This is Sandy's take on making a simple yet powerful enough HTTP library. Inspired by python's requests.
Motivation
When it comes to making network requests, I find myself writing a lot of repetitive go code, you know the gist of getting a json response,
req, err := http.NewRequestWithContext(context, method, URLpath, body)
if err != nil { ... }
params := req.URL.Query()
params.Add(key, value)
// more great parameters you need
req.URL.RawQuery = params.Encode()
resp, err := client.Do(req)
if err != nil { ... }
defer resp.Body.Close()
// do a response status check if needed...
ans := &SomeStruct{}
if err != json.NewDecoder(resp.Body).Decode(ans); err != nil { ... }
// whatever other magic you need to do
This is still a condensed version! The example above skips a couple of steps for brevity, like setting timeouts, deadlines, proper reading, buffering, progress, etc.
You can end up making something of your own, but repeating the same code has many issues, such as forgetting to close the response body or set proper contexts with plenty more.
Examples
What if instead, all you had to write was
ans := &SomeStruct{}
err := haruhi.URL(URLpath).
Method(method).
Params(params).
Body(body).
Timeout(time.Minute).
ResponseJSON(ans)
and it did everything for you? You can even simplify it with haruhi's sensible defaults, such as
running a GET request by default, etc, so you could even do
respStr, err := haruhi.URL(url).Get()
Haruhi of course, supports more funtionality that is aimed to be simple and straight-forward. Entire codebase is documented, so head on to go docs to see what else she can do.
Bad inputs, like setting handlers to nil will be ignored. Fatal errors when creating a request
through Go or serializing bodies will be called with log.Fatalf.
Have fun requesting!
Similar projects
There is a golang requests project by Carl M. Johnson, who wrote a nice blog post about needing a nice http library to avoid many of mistakes mentioned above. It has been around for much longer (around 2 years?) and I've tried to use it. However, it may have been me misreading methods, or something else, but my requests weren't passing as I expected them to. And it's a powerful library, which can do roundtrip logging, redirect checkers, etc. However, most of the time, I want a dead-simple interface that "just works" and stays close to how I make fully proper go requests. Almost as if it's a bunch of macros.
I also found an older requests library, which I've never used but wanted to mention nonetheless.
Why Haruhi?
Because Endless Eight is a cinematic masterpiece and Haruhi is life itself.
Documentation
¶
Index ¶
- type Request
- func (r *Request) BasicAuth(username, password string) *Request
- func (r *Request) Body(body io.Reader) *Request
- func (r *Request) BodyBytes(body []byte) *Request
- func (r *Request) BodyFormData(body url.Values) *Request
- func (r *Request) BodyJson(body any) *Request
- func (r *Request) BodyString(body string) *Request
- func (r *Request) BodyXML(body any) *Request
- func (r *Request) Client(client *http.Client) *Request
- func (r *Request) Context(ctx context.Context) *Request
- func (r *Request) Deadline(deadline *time.Time) *Request
- func (r *Request) Delete() (string, error)
- func (r *Request) ErrorHandler(errorHandler func(*http.Response, error) error) *Request
- func (r *Request) Get() (string, error)
- func (r *Request) Header(name, value string) *Request
- func (r *Request) Headers(headers http.Header) *Request
- func (r *Request) IfNotExpectedStatusCode(statusCode int, handler func(*http.Response) error) *Request
- func (r *Request) Method(method string) *Request
- func (r *Request) Param(name, value string) *Request
- func (r *Request) Params(params url.Values) *Request
- func (r *Request) Path(path string) *Request
- func (r *Request) Post() (string, error)
- func (r *Request) Put() (string, error)
- func (r *Request) Request() (*http.Request, context.CancelFunc, error)
- func (r *Request) Response() (resp *http.Response, cancel context.CancelFunc, err error)
- func (r *Request) ResponseBody() (body io.ReadCloser, cancel context.CancelFunc, err error)
- func (r *Request) ResponseBuffer() (*bytes.Buffer, error)
- func (r *Request) ResponseBytes() ([]byte, error)
- func (r *Request) ResponseJson(v any) error
- func (r *Request) ResponseString() (string, error)
- func (r *Request) ResponseXML(v any) error
- func (r *Request) StatusCodeHandler(statusCode int, handler func(*http.Response) error) *Request
- func (r *Request) Timeout(timeout time.Duration) *Request
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request is an internal "staging" struct used when we want to track of what kind of Request user wants to make.
func URL ¶
URL will start building a request with the given URL (scheme+domain), an example is `https://go.dev` (notice without the path or parameters).
func (*Request) BasicAuth ¶
BasicAuth sets the request's Authorization header to use HTTP Basic Authentication with the provided username and password.
func (*Request) BodyFormData ¶
BodyFormData will take values and send them as formdata.
func (*Request) BodyJson ¶
BodyXML will encode given interfact/instance into JSON and use that as body.
func (*Request) BodyString ¶
BodyString will use string as body.
func (*Request) BodyXML ¶
BodyXML will encode given interfact/instance into XML and use that as body.
func (*Request) Deadline ¶
Deadline for the request (absolute time), defaults to `nil` (no deadline).
func (*Request) ErrorHandler ¶
ErrorHandler will set the error handler to be called if the request fails.
func (*Request) Header ¶ added in v0.2.0
Headers will record headers to use in the request, will override defaults.
func (*Request) Headers ¶
Headers will record headers to use in the request, will override defaults.
func (*Request) IfNotExpectedStatusCode ¶ added in v0.2.0
func (r *Request) IfNotExpectedStatusCode(statusCode int, handler func(*http.Response) error) *Request
IfNotExpectedStatusCode will set the handler to be called if the request does not return the expected status code.
func (*Request) Method ¶
Method to use in HTTP request, defaults to "GET" -- recommend using `http.Method...` constants.
func (*Request) ResponseBody ¶
func (r *Request) ResponseBody() (body io.ReadCloser, cancel context.CancelFunc, err error)
Make a request (parked) and get the body reader (needs closing) with cancel.
func (*Request) ResponseBuffer ¶
Make a request and get the response as `*bytes.Buffer`.
func (*Request) ResponseBytes ¶
Make a request and get the response as bytes.
func (*Request) ResponseJson ¶
Make a request and decode the JSON response into given interface.
func (*Request) ResponseString ¶
Make a request and get the response as a string.
func (*Request) ResponseXML ¶
Make a request and decode the XML response into given interface.
func (*Request) StatusCodeHandler ¶ added in v0.2.0
StatusCodeHandler will set the handler to be called if the request returns given status code.
Source Files