httpclient

Documentation

Overview

Package httpclient provide a HTTP client factory for all code that need to make API calls. This makes it possible for auth and actual API client code to share properties such as whether the connections should be made using HTTP instead of HTTPS (Insecure) or whether server certificate checking should be bypassed (NoCertCheck). The HTTP clients created with this package also have built-in support for dumping requests and responses, the "Debug" dump format produces:

https://us-3.rightscale.com/api/clouds GET /api/clouds HTTP/1.1

GET https://us-3.rightscale.com/api/clouds Host: us-3.rightscale.com User-Agent: rsc/dev-unknown-branch Content-Type: application/json X-Api-Version: 1.5 Accept-Encoding: gzip ==> HTTP/1.1 200 OK Content-Length: 17224 Cache-Control: private, max-age=0, must-revalidate Connection: keep-alive Content-Type: application/vnd.rightscale.cloud+json;type=collection;charset=utf-8 Date: Fri, 10 Jul 2015 22:01:35 GMT Status: 200 OK Strict-Transport-Security: max-age=31536000; includeSubdomains; X-Request-Uuid: 3b036a56a5b04b35a94dbaf8240f1016

Index

• Constants
• Variables
• func ShortToken() string
• type Format
  • func (f Format) IsDebug() bool
  • func (f Format) IsJSON() bool
  • func (f Format) IsRecord() bool
  • func (f Format) IsVerbose() bool
• type HTTPClient
  • func New() HTTPClient
  • func NewNoRedirect() HTTPClient

Constants

const UA = "rsc/dev-unknown-branch"

UA is the default user agent. The value gets overridden by build scripts for release builds.

Variables

var (
	// DumpFormat dictates how HTTP requests and responses are logged: NoDump prevents logging
	// altogether, Debug generates logs in human readable format and JSON in JSON format.
	// Verbose causes all headers to be logged - including sensitive ones.
	DumpFormat Format

	// Insecure dictates whether HTTP (true) or HTTPS (false) should be used to connect to the
	// API endpoints.
	Insecure bool

	// NoCertCheck dictates whether the SSL handshakes should bypass X509 certificate
	// validation (true) or not (false).
	NoCertCheck bool

	// ResponseHeaderTimeout if non-zero, specifies the amount of
	// time to wait in seconds for a server's response headers after fully
	// writing the request (including its body, if any). This
	// time does not include the time to read the response body.
	ResponseHeaderTimeout = 300 * time.Second

	// HiddenHeaders lists headers that should not be logged unless DumpFormat is Verbose.
	HiddenHeaders = map[string]bool{"Authorization": true, "Cookie": true}
)

var (
	OsStderr io.Writer = os.Stderr
)

For tests

Functions

func ShortToken

func ShortToken() string

ShortToken creates a 6 bytes unique string. Not meant to be cryptographically unique but good enough for logs.

Types

type Format

type Format int

Format is the request/response dump format.

const (
	// NoDump is the default value for DumpFormat.
	NoDump Format = 1 << iota
	// Debug formats the dumps in human readable format, the use of this flag is exclusive with
	// JSON.
	Debug
	// JSON formats the dumps in JSON, the use of this flag is exclusive with Debug.
	JSON
	// Verbose enables the dumps for all requests and auth headers.
	Verbose
	// Record causes the dumps to be written to the recorder file descriptor (used by tests).
	Record
)

func (Format) IsDebug

func (f Format) IsDebug() bool

IsDebug is a convenience wrapper that returns true if the Debug bit is set on the flag.

func (Format) IsJSON

func (f Format) IsJSON() bool

IsJSON is a convenience wrapper that returns true if the JSON bit is set on the flag.

func (Format) IsRecord

func (f Format) IsRecord() bool

IsRecord is a convenience wrapper that returns true if the Record bit is set on the flag.

func (Format) IsVerbose

func (f Format) IsVerbose() bool

IsVerbose is a convenience wrapper that returns true if the Verbose bit is set on the flag.

type HTTPClient

type HTTPClient interface {
	// Do makes a regular http request and returns the response/error.
	Do(req *http.Request) (*http.Response, error)

	// DoWithContext performs a request and is context-aware.
	DoWithContext(ctx context.Context, req *http.Request) (*http.Response, error)

	// DoHidden prevents logging, useful for requests made during authorization.
	DoHidden(req *http.Request) (*http.Response, error)

	// DoHiddenWithContext prevents logging and performs a context-aware request.
	DoHiddenWithContext(ctx context.Context, req *http.Request) (*http.Response, error)
}

HTTPClient makes it easier to stub HTTP clients for testing.

func New

func New() HTTPClient

New returns an HTTP client using the settings specified by this package variables.

func NewNoRedirect

func NewNoRedirect() HTTPClient

NewNoRedirect returns an HTTP client that does not follow redirects.