rustic

README

Rustic - A minimalistic library in Go for HTTP Client and tracing constructs

Yet another HTTP Client in go with very simple yet essential features

Features of HTTPClient

• http client with type safety
• Different http configurations support - Timeout, Headers, QueryParams, FormParams, MultipartFormParams, CircuitBreaker
• Supports GET, POST, POSTMultiPartFormData, POSTFormData, PUT
  • DELETE, PATCH
• Add metrics either via open telemetry or prometheus metrics
• Add support for retries, it should have either default/custom or without any retrier

Features of Tracing constructs

• supports opentelemetry - stdOut and OTLP Http exporter
• tracing middleware for echo v3 and v4

NOTE: For circuit breaker https://github.com/sony/gobreaker is used.

Usage

go get github.com/rag594/rustic

How to use it

HTTP Client

// UserPost represents the post/blog by a specific user 
type UserPost struct {
	UserId int    `json:"userId"`
	Id     int    `json:"id"`
	Title  string `json:"title"`
	Body   string `json:"body"`
}

Initialise tracer for HTTP client

shutdown := rusticTracer.InitTracer("microserviceA", "dev", rusticTracer.StdOutExporter())
defer shutdown()

// configure your http client
client := httpClient.NewHTTPClient(httpClient.WithTraceEnabled(true))
url := "https://jsonplaceholder.typicode.com/posts"

// define your query params
params := url2.Values{}
params.Add("userId", "1")

// configure your circuit breaker(currently only sony circuit breaker is supported)
st := &gobreaker.Settings{}
st.Name = "HTTP GET"

st.ReadyToTrip = func(counts gobreaker.Counts) bool {
        failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
        return counts.Requests >= 3 && failureRatio >= 0.6
}

cb := gobreaker.NewCircuitBreaker[any](*st)

Trigger HTTP client

post, err := rustic.GET[[]UserPost](context.Background(),
        url,
        rustic.WithQueryParams(params),
        rustic.WithHttpClient(client),
        rustic.WithTimeout(time.Duration(1)*time.Second),
        rustic.WithCircuitBreaker(cb), 
			)
    if err != nil {
        fmt.Println(err)
    }

    fmt.Println(post)

Opentelementry Tracing

Using with Echo Framework

Initialise the trace with service name, environment and exporter()below is an OTLP exporter with configured telemetry backend. That's it, you have configured the traces

// you can try out with tracer.StdOutExporter() in your localhost
	shutdown := rusticTracer.InitTracer("userService", "dev", rusticTracer.OTLPExporter("localhost", "4318"))

	defer shutdown()
	e.Use(rusticTracer.Echov4TracerMiddleware("userService"))

You can run the sample under example/echoTraceMiddleware and observe the trace as below:

Important information wrt context

1. If you pass the context as nil, then context is set as Background
2. If you pass the timeout, new context is derived from parent context
3. If you wish to maintain context timeout at the parent level, do not pass timeout

Documentation

Index

• func GET[Res any](ctx context.Context, url string, opts ...HTTPConfigOptions) (*Res, error)
• func POST[Req, Res any](ctx context.Context, url string, req *Req, opts ...HTTPConfigOptions) (*Res, error)
• func POSTFormData[Res any](ctx context.Context, url string, opts ...HTTPConfigOptions) (*Res, error)
• func POSTMultiPartFormData[Res any](ctx context.Context, url string, files map[string]string, ...) (*Res, error)
• func PUT[Req, Res any](ctx context.Context, url string, req *Req, opts ...HTTPConfigOptions) (*Res, error)
• type HTTPConfig
• type HTTPConfigOptions
  • func WithCircuitBreaker(c *gobreaker.CircuitBreaker[any]) HTTPConfigOptions
  • func WithFormParams(c netUrl.Values) HTTPConfigOptions
  • func WithHeaders(c http.Header) HTTPConfigOptions
  • func WithHttpClient(c *httpClient.HTTPClient) HTTPConfigOptions
  • func WithMultiPartFormParams(c map[string]string) HTTPConfigOptions
  • func WithQueryParams(c netUrl.Values) HTTPConfigOptions
  • func WithTimeout(t time.Duration) HTTPConfigOptions

Functions

func GET

func GET[Res any](ctx context.Context, url string, opts ...HTTPConfigOptions) (*Res, error)

GET http method with Res as response type

func POST

func POST[Req, Res any](ctx context.Context, url string, req *Req, opts ...HTTPConfigOptions) (*Res, error)

POST http method with Req as request type and Res as response type

func POSTFormData

func POSTFormData[Res any](ctx context.Context, url string, opts ...HTTPConfigOptions) (*Res, error)

POSTFormData with Res as response type and allows application/x-www-form-urlencoded -> formData

func POSTMultiPartFormData

func POSTMultiPartFormData[Res any](ctx context.Context, url string, files map[string]string, opts ...HTTPConfigOptions) (*Res, error)

POSTMultiPartFormData with Res as response type, map of files with key as fieldName and value as filePath

func PUT

func PUT[Req, Res any](ctx context.Context, url string, req *Req, opts ...HTTPConfigOptions) (*Res, error)

PUT http method with Req as request type and Res as response type

Types

type HTTPConfig

type HTTPConfig struct {
	HttpClient          *httpClient.HTTPClient
	Timeout             time.Duration
	Headers             http.Header
	QueryParams         netUrl.Values
	FormParams          netUrl.Values
	MultipartFormParams map[string]string
	CircuitBreaker      *gobreaker.CircuitBreaker[any] // currently only github.com/sony/gobreaker/v2 is supported
}

HTTPConfig different http configurations

type HTTPConfigOptions

type HTTPConfigOptions func(*HTTPConfig)

func WithCircuitBreaker

func WithCircuitBreaker(c *gobreaker.CircuitBreaker[any]) HTTPConfigOptions

func WithFormParams

func WithFormParams(c netUrl.Values) HTTPConfigOptions

func WithHeaders

func WithHeaders(c http.Header) HTTPConfigOptions

func WithHttpClient

func WithHttpClient(c *httpClient.HTTPClient) HTTPConfigOptions

func WithMultiPartFormParams

func WithMultiPartFormParams(c map[string]string) HTTPConfigOptions

func WithQueryParams

func WithQueryParams(c netUrl.Values) HTTPConfigOptions

func WithTimeout

func WithTimeout(t time.Duration) HTTPConfigOptions