rq

README

rq

A nicer interface for golang stdlib HTTP client

Documents

• rq: here
• client: here
• jar: here

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

go get -u github.com/ddo/rq

Getting started

Simple

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

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

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

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

Raw body

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

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

Client

Default

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

Custom Options

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

// 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

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

Cookies

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

Documentation

Index

• type Rq
  • func Delete(URL string) *Rq
  • func Get(URL string) *Rq
  • func Head(URL string) *Rq
  • func New(method, URL string) *Rq
  • func NewFromJSON(data []byte) (r *Rq, err error)
  • func Post(URL string) *Rq
  • func Put(URL string) *Rq
  • func (r *Rq) JSONify() ([]byte, error)
  • func (r *Rq) ParseRequest() (req *http.Request, err error)
  • func (r *Rq) Qs(key string, value ...string)
  • func (r *Rq) Send(key string, value ...string)
  • func (r *Rq) SendRaw(reader io.Reader)
  • func (r *Rq) Set(key string, value ...string)
  • func (rq *Rq) String() string
  • func (r *Rq) UnQs(key string)
  • func (r *Rq) UnSend(key string)
  • func (r *Rq) UnSendRaw()
  • func (r *Rq) UnSet(key string)

Types

type Rq

type Rq struct {
	URL    string `json:"url"`
	Method string `json:"method"`

	Query  map[string][]string `json:"query"`
	Form   map[string][]string `json:"form"`
	Header map[string][]string `json:"header"`

	Body io.Reader `json:"-"`
}

Rq contains nicer http request interface components

func Delete

func Delete(URL string) *Rq

Delete is a shortcut of #New

func Get

func Get(URL string) *Rq

Get is a shortcut of #New

func Head

func Head(URL string) *Rq

Head is a shortcut of #New

func New

func New(method, URL string) *Rq

New returms empty Rq object

func NewFromJSON

func NewFromJSON(data []byte) (r *Rq, err error)

NewFromJSON create Rq object from json

func Post

func Post(URL string) *Rq

Post is a shortcut of #New

func Put

func Put(URL string) *Rq

Put is a shortcut of #New

func (*Rq) JSONify

func (r *Rq) JSONify() ([]byte, error)

JSONify returns Rq object in json

func (*Rq) ParseRequest

func (r *Rq) ParseRequest() (req *http.Request, err error)

ParseRequest parses Rq as http.Request

func (*Rq) Qs

func (r *Rq) Qs(key string, value ...string)

Qs appends request query

func (*Rq) Send

func (r *Rq) Send(key string, value ...string)

Send appends request form

func (*Rq) SendRaw

func (r *Rq) SendRaw(reader io.Reader)

SendRaw sets request body directly and override the #Send

func (*Rq) Set

func (r *Rq) Set(key string, value ...string)

Set appends request header

func (*Rq) String

func (rq *Rq) String() string

func (*Rq) UnQs

func (r *Rq) UnQs(key string)

UnQs unsets request query

func (*Rq) UnSend

func (r *Rq) UnSend(key string)

UnSend unsets request form

func (*Rq) UnSendRaw

func (r *Rq) UnSendRaw()

UnSendRaw unsets request body

func (*Rq) UnSet

func (r *Rq) UnSet(key string)

UnSet unsets request header