cookiejarx

README

This package provides public version of net/http/cookiejar package from go 1.17.2 with all helper methods and storage interface publicly exported.

It aims to provide both pluggable storage for cookiejar implementations using this cookie jar and all required helpers to implement own http.CookieJar from scratch according to RFC 6265, including punycode hostname normalization.

By default, it uses same in-memory storage as original package, however when provided explicitly, it is possible to leverage additional methods of in-memory storage to implement simple external saving/loading and clearing of in-memory storage;

see

• InMemoryStorage.EntriesDump
• InMemoryStorage.EntriesRestore
• InMemoryStorage.EntriesClear

Documentation

Overview

Package cookiejarx implements an in-memory RFC 6265-compliant http.CookieJar.

Index

• func CanonicalHost(host string) (string, error)
• func DefaultPath(path string) string
• func DomainAndType(host, domain string, psList PublicSuffixList) (string, bool, error)
• func HasDotSuffix(s, suffix string) bool
• func HasPort(host string) bool
• func IsIP(host string) bool
• func JarKey(host string, psl PublicSuffixList) string
• type Entry
  • func NewEntry(c *http.Cookie, now time.Time, defPath, host, key string, ...) (e Entry, remove bool, err error)
  • func (e *Entry) DomainMatch(host string) bool
  • func (e *Entry) PathMatch(requestPath string) bool
  • func (e *Entry) ShouldSend(https bool, host, path string) bool
• type InMemoryStorage
  • func NewInMemoryStorage() *InMemoryStorage
  • func (s *InMemoryStorage) Entries(https bool, host, path, key string, now time.Time) (entries []*Entry)
  • func (s *InMemoryStorage) EntriesClear()
  • func (s *InMemoryStorage) EntriesDump() (entries []*Entry)
  • func (s *InMemoryStorage) EntriesRestore(entries []*Entry)
  • func (s *InMemoryStorage) RemoveEntry(key, id string)
  • func (s *InMemoryStorage) SaveEntry(entry *Entry)
• type Jar
  • func New(o *Options) (*Jar, error)
  • func (j *Jar) Cookies(u *url.URL) (cookies []*http.Cookie)
  • func (j *Jar) SetCookies(u *url.URL, cookies []*http.Cookie)
• type Options
• type PublicSuffixList
• type Storage

Examples

• New

Functions

func CanonicalHost

func CanonicalHost(host string) (string, error)

CanonicalHost strips port from host if present and returns the canonicalized host name.

func DefaultPath

func DefaultPath(path string) string

DefaultPath returns the directory part of an URL's path according to RFC 6265 section 5.1.4.

func DomainAndType

func DomainAndType(host, domain string, psList PublicSuffixList) (string, bool, error)

DomainAndType determines the cookie's domain and hostOnly attribute.

func HasDotSuffix

func HasDotSuffix(s, suffix string) bool

HasDotSuffix reports whether s ends in "."+suffix.

func HasPort

func HasPort(host string) bool

HasPort reports whether host contains a port number. host may be a host name, an IPv4 or an IPv6 address.

func IsIP

func IsIP(host string) bool

IsIP reports whether host is an IP address.

func JarKey

func JarKey(host string, psl PublicSuffixList) string

JarKey returns the key to use for a jar.

Types

type Entry

type Entry struct {
	Name       string
	Value      string
	Domain     string
	Path       string
	SameSite   string
	Key        string
	ID         string
	Secure     bool
	HttpOnly   bool
	Persistent bool
	HostOnly   bool
	Expires    time.Time
	Creation   time.Time
	LastAccess time.Time
}

Entry is the internal representation of a cookie.

func NewEntry

func NewEntry(
	c *http.Cookie,
	now time.Time,
	defPath, host, key string,
	psList PublicSuffixList,
) (e Entry, remove bool, err error)

NewEntry creates an Entry from a http.Cookie c. now is the current time and is compared to c.Expires to determine deletion of c. defPath and host are the default-path and the canonical host name of the URL c was received from.

remove records whether the jar should delete this cookie, as it has already expired with respect to now. In this case, e may be incomplete, but it will be valid to use e.ID

A malformed c.Domain will result in an error.

func (*Entry) DomainMatch

func (e *Entry) DomainMatch(host string) bool

DomainMatch implements "domain-match" of RFC 6265 section 5.1.3.

func (*Entry) PathMatch

func (e *Entry) PathMatch(requestPath string) bool

PathMatch implements "path-match" according to RFC 6265 section 5.1.4.

func (*Entry) ShouldSend

func (e *Entry) ShouldSend(https bool, host, path string) bool

ShouldSend determines whether e's cookie qualifies to be included in a request to host/path. It is the caller's responsibility to check if the cookie is expired.

type InMemoryStorage

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

InMemoryStorage provides thread-safe in-memory entry storage with predictable entry sorting

func NewInMemoryStorage

func NewInMemoryStorage() *InMemoryStorage

NewInMemoryStorage returns new InMemoryStorage instance

func (*InMemoryStorage) Entries

func (s *InMemoryStorage) Entries(https bool, host, path, key string, now time.Time) (entries []*Entry)

Entries in-memory implementation of Storage.Entries

func (*InMemoryStorage) EntriesClear

func (s *InMemoryStorage) EntriesClear()

EntriesClear empties current in-memory storage

func (*InMemoryStorage) EntriesDump

func (s *InMemoryStorage) EntriesDump() (entries []*Entry)

EntriesDump returns all entries persisted in in-memory storage

func (*InMemoryStorage) EntriesRestore

func (s *InMemoryStorage) EntriesRestore(entries []*Entry)

EntriesRestore adds provide entries to current in-memory storage

func (*InMemoryStorage) RemoveEntry

func (s *InMemoryStorage) RemoveEntry(key, id string)

RemoveEntry in-memory implementation of Storage.RemoveEntry

func (*InMemoryStorage) SaveEntry

func (s *InMemoryStorage) SaveEntry(entry *Entry)

SaveEntry in-memory implementation of Storage.SaveEntry

type Jar

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

Jar implements the http.CookieJar interface from the net/http package.

func New

func New(o *Options) (*Jar, error)

New returns a new cookie jar. A nil *Options is equivalent to a zero Options.

Example

// Start a server to give us cookies.
ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	if cookie, err := r.Cookie("Flavor"); err != nil {
		http.SetCookie(w, &http.Cookie{Name: "Flavor", Value: "Chocolate Chip"})
	} else {
		cookie.Value = "Oatmeal Raisin"
		http.SetCookie(w, cookie)
	}
}))
defer ts.Close()

u, err := url.Parse(ts.URL)
if err != nil {
	log.Fatal(err)
}

// All users of cookiejar should import "golang.org/x/net/publicsuffix"
jar, err := cookiejar.New(&cookiejar.Options{PublicSuffixList: publicsuffix.List})
if err != nil {
	log.Fatal(err)
}

client := &http.Client{
	Jar: jar,
}

if _, err = client.Get(u.String()); err != nil {
	log.Fatal(err)
}

fmt.Println("After 1st request:")
for _, cookie := range jar.Cookies(u) {
	fmt.Printf("  %s: %s\n", cookie.Name, cookie.Value)
}

if _, err = client.Get(u.String()); err != nil {
	log.Fatal(err)
}

fmt.Println("After 2nd request:")
for _, cookie := range jar.Cookies(u) {
	fmt.Printf("  %s: %s\n", cookie.Name, cookie.Value)
}

Output:

After 1st request:
  Flavor: Chocolate Chip
After 2nd request:
  Flavor: Oatmeal Raisin

func (*Jar) Cookies

func (j *Jar) Cookies(u *url.URL) (cookies []*http.Cookie)

Cookies implements the Cookies method of the http.CookieJar interface.

It returns an empty slice if the URL's scheme is not HTTP or HTTPS.

func (*Jar) SetCookies

func (j *Jar) SetCookies(u *url.URL, cookies []*http.Cookie)

SetCookies implements the SetCookies method of the http.CookieJar interface.

It does nothing if the URL's scheme is not HTTP or HTTPS.

type Options

type Options struct {
	// PublicSuffixList is the public suffix list that determines whether
	// an HTTP server can set a cookie for a domain.
	//
	// A nil value is valid and may be useful for testing but it is not
	// secure: it means that the HTTP server for foo.co.uk can set a cookie
	// for bar.co.uk.
	PublicSuffixList PublicSuffixList

	// Storage is the cookie entry persistence implementation.
	//
	// If not provided, InMemoryStorage will be used.
	Storage Storage
}

Options are the options for creating a new Jar.

type PublicSuffixList

type PublicSuffixList interface {
	// PublicSuffix returns the public suffix of domain.
	//
	// TODO: specify which of the caller and callee is responsible for IP
	// addresses, for leading and trailing dots, for case sensitivity, and
	// for IDN/Punycode.
	PublicSuffix(domain string) string

	// String returns a description of the source of this public suffix
	// list. The description will typically contain something like a time
	// stamp or version number.
	String() string
}

PublicSuffixList provides the public suffix of a domain. For example:

• the public suffix of "example.com" is "com",
• the public suffix of "foo1.foo2.foo3.co.uk" is "co.uk", and
• the public suffix of "bar.pvt.k12.ma.us" is "pvt.k12.ma.us".

Implementations of PublicSuffixList must be safe for concurrent use by multiple goroutines.

An implementation that always returns "" is valid and may be useful for testing but it is not secure: it means that the HTTP server for foo.com can set a cookie for bar.com.

A public suffix list implementation is in the package golang.org/x/net/publicsuffix.

type Storage

type Storage interface {
	// SaveEntry stores provided entry in persistent repository
	// Entry.Key and Entry.ID shall be used for subsequent lookups
	SaveEntry(entry *Entry)

	// RemoveEntry removes entry from persistent repository with provided
	// key - entry public suffix
	// id - entry unique id
	RemoveEntry(key, id string)

	// Entries returns entries matching URL parameters:
	// https schema, host/path, public suffix key and current time
	Entries(https bool, host, path, key string, now time.Time) (entries []*Entry)
}

Storage is a persistent storage for cookiejar entries

Implementations of Storage must be safe for concurrent use by multiple goroutines.