httpc

README

httpc

A tiny HTTP Client wrapper based on Go http package.

Installing

WARNING

API is not yet stable and we might introduce breaking changes until we reached version v1.0.0. See Breaking Changes section for deprecation notes.

go get -u github.com/nbs-go/httpc

Breaking Changes

v0.7.0

• Revert Go minimum version to 1.17
• Remove built-in OpenTelemetry instrumentation, replaced with SetGlobalTransporterOverrider() function

v0.6.0

• Upgrade Go minimum version to 1.19

Usage

TODO

Enable OpenTelemetry Instrumentation

package main

import (
	"github.com/nbs-go/httpc"
	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
	"net/http"
)

// On init() package, SetGlobalTransporterOverrider to enable OpenTelemetry instrumentation
// across all initiated httpc.Client
func init() {
	httpc.SetGlobalTransporterOverrider(func(existingTransporter http.RoundTripper) http.RoundTripper {
		// Wrap existingTransporter with otelhttp.Transporter to enable instrumentation
		return otelhttp.NewTransport(existingTransporter)
	})
}

Contributors

Documentation

Index

• Constants
• func SetGlobalTransporterOverrider(fn TransporterOverrider)
• type Client
  • func NewClient(baseUrl string, args ...SetClientOptionsFn) *Client
  • func (c *Client) DoRequest(ctx context.Context, method Method, endpointPath string, ...) (*http.Response, []byte, error)
• type ContextKey
• type Instrumentation
• type Method
• type PreRequestFn
• type RESTRequest
  • func NewRESTRequest(c *Client, method Method, endpointPath string, args ...SetRequestOptionFn) *RESTRequest
  • func (rr *RESTRequest) AddHeader(args ...string) *RESTRequest
  • func (rr *RESTRequest) AddOption(fn ...SetRequestOptionFn) *RESTRequest
  • func (rr *RESTRequest) AddQuery(args ...string) *RESTRequest
  • func (rr *RESTRequest) Body(b interface{}) *RESTRequest
  • func (rr *RESTRequest) Do(ctx context.Context, dst interface{}) (*http.Response, error)
  • func (rr *RESTRequest) PreRequest(fn PreRequestFn) *RESTRequest
• type SetClientOptionsFn
  • func DisableHTTP2() SetClientOptionsFn
  • func LogDump(enable bool) SetClientOptionsFn
  • func Namespace(n string) SetClientOptionsFn
• type SetRequestOptionFn
  • func AddHeader(args ...string) SetRequestOptionFn
  • func AddQuery(args ...string) SetRequestOptionFn
  • func DisableCanonicalHeader() SetRequestOptionFn
  • func PreRequest(fn PreRequestFn) SetRequestOptionFn
  • func SetBody(body interface{}) SetRequestOptionFn
  • func SetJsonBody(body interface{}) SetRequestOptionFn
  • func SetUrlEncodedFormBody(body url.Values) SetRequestOptionFn
  • func Timeout(ms int) SetRequestOptionFn
• type TransporterOverrider

Constants

const (
	MimeTypeJson           = "application/json"
	MimeTypeUrlEncodedForm = "application/x-www-form-urlencoded"
)

const (
	ContextRequestId = iota + 1
)

const (
	HeaderContentType = "Content-Type"
)

const (
	InstrumentationOpenTelemetry = iota + 1
)

Functions

func SetGlobalTransporterOverrider

func SetGlobalTransporterOverrider(fn TransporterOverrider)

SetGlobalTransporterOverrider set value to global overrideTransporter function. This function will override every transporter initiated afterward. Example use case is to wrap http.Client Transporter field with instrumentation such as OpenTelemetry otelhttp package (go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(baseUrl string, args ...SetClientOptionsFn) *Client

func (*Client) DoRequest

func (c *Client) DoRequest(ctx context.Context, method Method, endpointPath string, args ...SetRequestOptionFn) (*http.Response, []byte, error)

type ContextKey

type ContextKey int8

type Instrumentation

type Instrumentation int8

type Method

type Method = string

const (
	MethodGet     Method = "GET"
	MethodHead    Method = "HEAD"
	MethodPost    Method = "POST"
	MethodPut     Method = "PUT"
	MethodPatch   Method = "PATCH" // RFC 5789
	MethodDelete  Method = "DELETE"
	MethodConnect Method = "CONNECT"
	MethodOptions Method = "OPTIONS"
	MethodTrace   Method = "TRACE"
)

Common HTTP methods.

Unless otherwise noted, these are defined in RFC 7231 section 4.3.

type PreRequestFn

type PreRequestFn func(req *http.Request, reqBody []byte)

type RESTRequest

type RESTRequest struct {
	Id string
	// contains filtered or unexported fields
}

func NewRESTRequest

func NewRESTRequest(c *Client, method Method, endpointPath string, args ...SetRequestOptionFn) *RESTRequest

NewRESTRequest creates a builder for REST API style request that use json as request and response body

func (*RESTRequest) AddHeader

func (rr *RESTRequest) AddHeader(args ...string) *RESTRequest

func (*RESTRequest) AddOption

func (rr *RESTRequest) AddOption(fn ...SetRequestOptionFn) *RESTRequest

func (*RESTRequest) AddQuery

func (rr *RESTRequest) AddQuery(args ...string) *RESTRequest

func (*RESTRequest) Body

func (rr *RESTRequest) Body(b interface{}) *RESTRequest

func (*RESTRequest) Do

func (rr *RESTRequest) Do(ctx context.Context, dst interface{}) (*http.Response, error)

Do prepare REST request, do and parse response body to JSON dst

func (*RESTRequest) PreRequest

func (rr *RESTRequest) PreRequest(fn PreRequestFn) *RESTRequest

type SetClientOptionsFn

type SetClientOptionsFn func(o *clientOptions)

func DisableHTTP2

func DisableHTTP2() SetClientOptionsFn

DisableHTTP2 disable HTTP/2 alternate protocol

func LogDump

func LogDump(enable bool) SetClientOptionsFn

LogDump enable log HTTP request and response dump

func Namespace

func Namespace(n string) SetClientOptionsFn

Namespace override default Client namespace value

type SetRequestOptionFn

type SetRequestOptionFn func(o *requestOptions)

func AddHeader

func AddHeader(args ...string) SetRequestOptionFn

func AddQuery

func AddQuery(args ...string) SetRequestOptionFn

func DisableCanonicalHeader

func DisableCanonicalHeader() SetRequestOptionFn

func PreRequest

func PreRequest(fn PreRequestFn) SetRequestOptionFn

func SetBody

func SetBody(body interface{}) SetRequestOptionFn

func SetJsonBody

func SetJsonBody(body interface{}) SetRequestOptionFn

func SetUrlEncodedFormBody

func SetUrlEncodedFormBody(body url.Values) SetRequestOptionFn

func Timeout

func Timeout(ms int) SetRequestOptionFn

type TransporterOverrider

type TransporterOverrider func(existing http.RoundTripper) http.RoundTripper

TransporterOverrider is a function to override how http client Transporter value. Could be used to wrap existing client Transporter (rt) for instrumentation or override Transporter value