chttp

README

chttp

Cooked HTTP — a standard golang HTTP Client wrapper that adds a cookie jar with user-defined cookies, and a customised transport.

Features:

• Cookie jar initialization and seeding for a target domain.
• Option-based request customization (WithUserAgent).
• Optional uTLS transport (WithUTLS) with Chrome ClientHello emulation by default.
• HTTP/2 connection pooling for uTLS transport — connections are reused across requests.
• Transport hooks via transport.FuncTransport (BeforeReq / AfterReq).

Simple usage:

import "github.com/rusq/chttp/v2"

func getSomething() error {
	cookies := readFromFile()
	cl, err := chttp.New("https://slack.com", cookies)
	if err != nil {
		return err
	}

	resp, err := cl.Get("url") // executes with cookies from the jar
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	// do something with resp
	return nil
}

uTLS usage:

import (
	"github.com/rusq/chttp/v2"
	utls "github.com/refraction-networking/utls"
)

func getWithUTLS() error {
	cl, err := chttp.New(
		"https://example.com",
		nil,
		chttp.WithUTLS(&utls.Config{}),
		chttp.WithUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"),
	)
	if err != nil {
		return err
	}
	defer chttp.Close(cl) // releases pooled connections

	resp, err := cl.Get("https://example.com")
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	return nil
}

Integration tests:

• Unit tests: go test ./...
• External HTTPS integration tests (opt-in):
  • CHTTP_RUN_INTEGRATION_TESTS=1 go test ./transport -run ExternalHTTPSIntegration
  • CHTTP_RUN_INTEGRATION_TESTS=1 TEST_DEBUG=1 go test ./transport -run ExternalHTTPSIntegration
    • when TEST_DEBUG=1 is set, integration responses are saved as <host>.html in the current directory.

Makefile shortcuts:

• make test runs go test ./... -race -cover
• make test_all runs integration tests with race+coverage enabled

See package documentation if you'd like to read more.

Documentation

Overview

Package chttp (Cooked HTTP) provides a wrapper around http.Client with cookies, that are added to each request. It also allows to use custom Transport, which wraps the default transport and calls the user-defined function before and after the request.

Index

• func Close(cl *http.Client) error
• func CookiesToPtr(cookies []http.Cookie) []*http.Cookie
• func Must(cl *http.Client, err error) *http.Client
• func New(cookieDomain string, cookies []*http.Cookie, opts ...Option) (*http.Client, error)
• func NewWithTransport(cookieDomain string, cookies []*http.Cookie, rt http.RoundTripper) (*http.Client, error)
• type Option
  • func WithUTLS(cfg *utls.Config) Option
  • func WithUserAgent(ua string) Option

Functions

func Close

func Close(cl *http.Client) error

Close releases resources held by the client's transport. It is safe to call on clients whose transport does not require cleanup (e.g. FuncTransport) — in that case it is a no-op.

func CookiesToPtr

func CookiesToPtr(cookies []http.Cookie) []*http.Cookie

CookiesToPtr is a convenience function that returns the slice with pointers to cookies.

func Must

func Must(cl *http.Client, err error) *http.Client

Must is a helper function to panic on error.

func New

func New(cookieDomain string, cookies []*http.Cookie, opts ...Option) (*http.Client, error)

New returns the HTTP client with cookies and default transport.

func NewWithTransport

func NewWithTransport(cookieDomain string, cookies []*http.Cookie, rt http.RoundTripper) (*http.Client, error)

NewWithTransport inits the HTTP client with cookies. It allows to use the custom Transport.

Types

type Option

type Option func(*options)

func WithUTLS

func WithUTLS(cfg *utls.Config) Option

WithUTLS enables uTLS transport. By default it emulates Chrome ClientHello.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent allows to set the User-Agent on each request.