Skip to main content

​
CookieJar interface

The CookieJar interface extends the standard http.CookieJar with additional functionality for managing cookies across requests. 
type CookieJar interface {
    http.CookieJar
    GetAllCookies() map[string][]*http.Cookie
}

​
Methods

​
SetCookies
func(u *url.URL, cookies []*http.Cookie)
Sets cookies for a specific URL. Inherited from http.CookieJar.
​
Cookies
func(u *url.URL) []*http.Cookie
Returns the cookies to send in a request to the given URL. Inherited from http.CookieJar.
​
GetAllCookies
func() map[string][]*http.Cookie
Returns all cookies stored in the jar, organized by host. This is a TLS Client-specific extension.

​
NewCookieJar

Creates a new cookie jar with optional configuration. 
func NewCookieJar(options ...CookieJarOption) CookieJar
​
options
...CookieJarOption
Variable number of cookie jar options. See below for available options.
Example: 
import tls_client "github.com/bogdanfinn/tls-client"

// Create a basic cookie jar
jar := tls_client.NewCookieJar()

// Create a cookie jar with options
jar := tls_client.NewCookieJar(
    tls_client.WithSkipExisting(),
    tls_client.WithDebugLogger(),
)

​
WithSkipExisting

Skip setting cookies that already exist in the jar. By default, existing cookies are overwritten when new cookies with the same name are set. 
func WithSkipExisting() CookieJarOption
Example: 
// Create a jar that won't overwrite existing cookies
jar := tls_client.NewCookieJar(
    tls_client.WithSkipExisting(),
)

// This is useful when you set cookies manually
// and don't want the server to overwrite them
u, _ := url.Parse("https://example.com")
jar.SetCookies(u, []*http.Cookie{
    {Name: "session", Value: "abc123"},
})

// Even if the server tries to set a new "session" cookie,
// it will be ignored because WithSkipExisting() is enabled
This option is useful when you need to maintain specific cookie values that shouldn’t be overwritten by server responses.

​
WithAllowEmptyCookies

Allow cookies with empty values to be stored in the jar. By default, empty cookies are filtered out. 
func WithAllowEmptyCookies() CookieJarOption
Example: 
// Allow cookies with empty values
jar := tls_client.NewCookieJar(
    tls_client.WithAllowEmptyCookies(),
)

// Now cookies like this will be stored
u, _ := url.Parse("https://example.com")
jar.SetCookies(u, []*http.Cookie{
    {Name: "empty_cookie", Value: ""},  // Will be kept with this option
})

​
WithDebugLogger

Enable debug logging for cookie operations. This will print cookie-related debug information to stdout. 
func WithDebugLogger() CookieJarOption
Example: 
// Enable debug logging for the cookie jar
jar := tls_client.NewCookieJar(
    tls_client.WithDebugLogger(),
)

// This will log when cookies are added, skipped, or filtered
Use WithDebugLogger() during development to understand how cookies are being handled.

​
WithLogger

Set a custom logger for cookie jar operations. 
func WithLogger(logger Logger) CookieJarOption
​
logger
Logger
A custom logger implementing the Logger interface. See the Logger API reference for details.
Example: 
// Use a custom logger
myLogger := &CustomLogger{}
jar := tls_client.NewCookieJar(
    tls_client.WithLogger(myLogger),
)

​
GetAllCookies example

Retrieve all cookies stored in the jar, organized by host: 
jar := tls_client.NewCookieJar()

// Set some cookies
u1, _ := url.Parse("https://example.com")
jar.SetCookies(u1, []*http.Cookie{
    {Name: "session", Value: "abc123"},
})

u2, _ := url.Parse("https://api.example.com")
jar.SetCookies(u2, []*http.Cookie{
    {Name: "token", Value: "xyz789"},
})

// Get all cookies
allCookies := jar.GetAllCookies()

// Output: map[string][]*http.Cookie
// {
//     "example.com": []*http.Cookie{...},
//     "api.example.com": []*http.Cookie{...},
// }

for host, cookies := range allCookies {
    fmt.Printf("Host: %s\n", host)
    for _, cookie := range cookies {
        fmt.Printf("  %s = %s\n", cookie.Name, cookie.Value)
    }
}
The cookie jar automatically filters cookies based on the following rules: By default, cookies with empty values are filtered out unless WithAllowEmptyCookies() is enabled. 
// Default behavior: empty cookies are filtered
jar := tls_client.NewCookieJar()

u, _ := url.Parse("https://example.com")
jar.SetCookies(u, []*http.Cookie{
    {Name: "valid", Value: "data"},
    {Name: "empty", Value: ""},  // Filtered out
})
Cookies with MaxAge < 0 are automatically filtered from requests. 
jar := tls_client.NewCookieJar()

u, _ := url.Parse("https://example.com")
jar.SetCookies(u, []*http.Cookie{
    {Name: "active", Value: "data", MaxAge: 3600},
    {Name: "deleted", Value: "old", MaxAge: -1},  // Will be excluded from requests
})

// When making a request, only "active" cookie will be sent
cookies := jar.Cookies(u)  // Only returns non-expired cookies
When multiple cookies have the same name, only the last one is kept: 
jar := tls_client.NewCookieJar()

u, _ := url.Parse("https://example.com")
jar.SetCookies(u, []*http.Cookie{
    {Name: "session", Value: "first"},
    {Name: "session", Value: "second"},  // This one wins
})

Build docs developers (and LLMs) love

Get started for freeTalk to us