client

client

Preface

This TLS Client is built upon https://github.com/Carcraftz/fhttp and https://github.com/Carcraftz/utls (https://github.com/refraction-networking/utls). Big thanks to all contributors so far. Sadly it seems that the original repositories from Carcraftz are not maintained anymore.

The module is published as github.com/malivvan/client.

What is TLS Fingerprinting?

Some people think it is enough to change the user-agent header of a request to let the server think that the client requesting a resource is a specific browser. Nowadays this is not enough, because the server might use a technique to detect the client browser which is called TLS Fingerprinting.

Even though this article is about TLS Fingerprinting in NodeJS it well describes the technique in general. https://httptoolkit.tech/blog/tls-fingerprinting-node-js/#how-does-tls-fingerprinting-work

Why is this library needed?

With this library you are able to create a http client implementing an interface which is similar to golangs net/http client interface. This TLS Client allows you to specify the Client (Browser and Version) you want to use, when requesting a server.

Features

• ✅ HTTP/1.1, HTTP/2, HTTP/3 - Full protocol support with automatic negotiation
• ✅ Protocol Racing - Chrome-like "Happy Eyeballs" for HTTP/2 vs HTTP/3
• ✅ TLS Fingerprinting - Mimic Chrome, Firefox, Safari, and other browsers
• ✅ HTTP/3 Fingerprinting - Accurate QUIC/HTTP/3 fingerprints matching real browsers
• ✅ WebSocket Support - Browser-mimicking WebSocket connection establishment (uTLS fingerprint, header order, permessage-deflate), fully integrated into the HttpClient interface
• ✅ WebTransport Support - HTTP/3 WebTransport sessions (streams + datagrams) whose QUIC connection establishment mimics the profile's browser
• ✅ Custom Header Ordering - Control the order of HTTP headers
• ✅ Proxy Support - HTTP and SOCKS5 proxies
• ✅ Cookie Jar Management - Built-in cookie handling
• ✅ Certificate Pinning - Enhanced security with custom certificate validation
• ✅ Bandwidth Tracking - Monitor upload/download bandwidth
• ✅ Language Bindings - Use from JavaScript (Node.js), Python, and C# via FFI

The HTTP, TLS and QUIC layers live in sibling modules under the same org (github.com/malivvan/http, github.com/malivvan/tls, github.com/malivvan/quic) so that the whole stack shares the same TLS fingerprinting machinery.

Interface

The HTTP Client interface extends the base net/http Client with additional functionality:

type HttpClient interface {
    GetCookies(u *url.URL) []*http.Cookie
    SetCookies(u *url.URL, cookies []*http.Cookie)
    SetCookieJar(jar http.CookieJar)
    GetCookieJar() http.CookieJar
    SetProxy(proxyUrl string) error
    GetProxy() string
    SetFollowRedirect(followRedirect bool)
    GetFollowRedirect() bool
    CloseIdleConnections()
    Do(req *http.Request) (*http.Response, error)
    Get(url string) (resp *http.Response, err error)
    Head(url string) (resp *http.Response, err error)
    Post(url, contentType string, body io.Reader) (resp *http.Response, err error)

    GetBandwidthTracker() BandwidthTracker
    GetDialer() proxy.ContextDialer
    GetTLSDialer() TLSDialerFunc

    AddPreRequestHook(hook PreRequestHookFunc)
    AddPostResponseHook(hook PostResponseHookFunc)
    ResetPreHooks()
    ResetPostHooks()

    DialWebSocket(ctx context.Context, url string, opts *websocket.DialOptions) (*websocket.Conn, *http.Response, error)
    DialWebTransport(ctx context.Context, url string, reqHdr http.Header) (*http.Response, *webtransport.Session, error)
}

Detailed Documentation

https://pkg.go.dev/github.com/malivvan/client

Quick Usage Example

package main

import (
	"fmt"
	"io"
	"log"

	"github.com/malivvan/http"
	client "github.com/malivvan/client"
	"github.com/malivvan/client/profiles"
)

func main() {
	jar := client.NewCookieJar()
	options := []client.HttpClientOption{
		client.WithTimeoutSeconds(30),
		client.WithClientProfile(profiles.Chrome_144),
		client.WithNotFollowRedirects(),
		client.WithCookieJar(jar), // create cookieJar instance and pass it as argument
	}

	client, err := client.NewHttpClient(client.NewNoopLogger(), options...)
	if err != nil {
		log.Println(err)
		return
	}

	req, err := http.NewRequest(http.MethodGet, "https://tls.peet.ws/api/all", nil)
	if err != nil {
		log.Println(err)
		return
	}

	req.Header = http.Header{
		"accept":                    {"*/*"},
		"accept-language":           {"de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7"},
		"user-agent":                {"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"},
		http.HeaderOrderKey: {
			"accept",
			"accept-language",
			"user-agent",
		},
	}

	resp, err := client.Do(req)
	if err != nil {
		log.Println(err)
		return
	}

	defer resp.Body.Close()

	log.Println(fmt.Sprintf("status code: %d", resp.StatusCode))

	readBytes, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Println(err)
		return
	}

	log.Println(string(readBytes))
}

WebSocket Usage

WebSocket connections are established directly through the HttpClient and inherit its full browser-mimicry configuration: the uTLS ClientHello fingerprint for the TLS handshake, the browser's handshake header order, the Sec-WebSocket-Extensions value and the permessage-deflate compression mode come from the client profile (Chrome writes lowercase host first, Firefox/Safari write Host first, etc.).

package main

import (
	"context"
	"log"

	"github.com/malivvan/http"
	"github.com/malivvan/http/websocket"
	client "github.com/malivvan/client"
	"github.com/malivvan/client/profiles"
)

func main() {
	client, err := client.NewHttpClient(nil,
		client.WithClientProfile(profiles.Chrome_133),
	)
	if err != nil {
		log.Fatal(err)
	}

	// opts may be nil: unset fields are filled from the client configuration.
	conn, resp, err := client.DialWebSocket(context.Background(), "wss://example.com/ws", &websocket.DialOptions{
		HTTPHeader: http.Header{
			"User-Agent": {"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36"},
			"Origin":     {"https://example.com"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close(websocket.StatusNormalClosure, "")

	_ = resp // WebSocket handshake response; its body must not be used.

	if err := conn.Write(context.Background(), websocket.MessageText, []byte("hello")); err != nil {
		log.Fatal(err)
	}

	typ, msg, err := conn.Read(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("received %s: %s", typ, msg)
}

WebTransport Usage

WebTransport sessions (HTTP/3 CONNECT) are also established through the HttpClient. The QUIC connection establishment mimics the profile's browser: the uTLS ClientHello is applied inside the QUIC handshake, so servers see the same TLS-level fingerprint as the real browser. Datagrams and stream-reset partial delivery are enabled as WebTransport requires.

package main

import (
	"context"
	"io"
	"log"

	"github.com/malivvan/http"
	client "github.com/malivvan/client"
	"github.com/malivvan/client/profiles"
)

func main() {
	client, err := client.NewHttpClient(nil,
		client.WithClientProfile(profiles.Chrome_133),
		client.WithInsecureSkipVerify(), // for local/self-signed WebTransport servers
	)
	if err != nil {
		log.Fatal(err)
	}

	resp, session, err := client.DialWebTransport(context.Background(),
		"https://example.com/webtransport",
		http.Header{"Origin": {"https://example.com"}},
	)
	if err != nil {
		log.Fatal(err)
	}
	defer session.CloseWithError(0, "")

	_ = resp // CONNECT response; its body must not be used.

	// Bidirectional stream (echo pattern).
	str, err := session.OpenStreamSync(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	if _, err := str.Write([]byte("hello webtransport")); err != nil {
		log.Fatal(err)
	}
	str.Close()
	echoed, err := io.ReadAll(str)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("echoed: %s", echoed)

	// Datagrams.
	if err := session.SendDatagram([]byte("ping")); err != nil {
		log.Fatal(err)
	}
	pong, err := session.ReceiveDatagram(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("pong: %s", pong)
}

Questions?

Open an issue at https://github.com/malivvan/client/issues