code review 5399043: net/http: Added interface for a cookie jar.

src/pkg/net/http/jar.go

-// Copyright 2009 The Go Authors. All rights reserved.
+// Copyright 2011 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 package http
 
 import (
         "net/url"
-        "strconv"
-        "strings"
-        "sync"
-        "time"
 )
 
-// CookieJar is the interface for a cookie jar.
+// A CookieJar manages storage and use of cookies in HTTP requests.·
+//
+// Implementations of CookieJar must be safe for concurrent use by multiple
+// goroutines.
 type CookieJar interface {
-        // Update will add the given cookies to the jar, update those allready
-        // in the jar and delete those which are requested to be deleted.
-        // The host is the host from which the Set-Cookie response headers
-        // have been recieved.  Invalid cookies (e.g. with a wildcard
-        // top level domain or cookies whose domain mismatches the host)
-        // are silently ignored.
-        Update(cookies []*Cookie, host string)
+        // SetCookies handles the receipt of the cookies in a reply for the·
+        // given URL.  It may or may not choose to save the cookies, depending·
+        // on the jar's policy and implementation.·
+        SetCookies(u *url.URL, cookies []*Cookie)
 
-        // Select will return a list of all cookies from the jar which
-        // should be sent to the given URL. I.e. unexpired, proper domain
-        // proper path, honouring secure and http-only settings
-        Select(u *url.URL) []*Cookie
+        // Cookies returns the cookies to send in a request for the given URL.
+        // It is up to the implementation to honor the standard cookie use·
+        // restrictions such as in RFC 6265.·
+        Cookies(u *url.URL) []*Cookie
 }
 
-// BlackHoleJar implements a black hole cookie jar: Whatever you stuck in
-// via Update will never come back out on a Select.
-type BlackHoleJar int
+type blackHoleJar struct{}
 
-func (bh BlackHoleJar) Update(cookies []*Cookie, host string) {}
-func (bh BlackHoleJar) Select(u *url.URL) []*Cookie           { return nil }
-
-// normalizeCookie returns a copy of cookie where the domain, path and expires
-// fields are properly set.·
-//  - The Domain of the returned cookie is the effective domain: www.domain.org will·
-//    become .www.domain.org
-//  - MaxAge is set to 0
-//  - Path is set to its default "/" if unset.
-//  - The Expires Time struct is cleared and the expiration time in UTC seconds
-//    is encoded in the Year field:  This allows for much quicker checks if
-//    the cookie is expired and can be replaced by a non-hack solution oce
-//    package time is updated. A value of 0 in the Year field indicates a session
-//    cookie.
-//    This hack will no longer be a hack once the new Time has come.
-// It will return nil for a expired cookie or if an invalid domain is
-// set (a top level domain like .net or anything like ??.??, eg. co.uk.·
-func normalizeCookie(cookie *Cookie, domain string) *Cookie {
-        c := *cookie
-
-        // Path defaults to /
-        if c.Path == "" {
-                c.Path = "/"
-        }
-
-        // Handle MaxAge.
-        switch true {
-        case c.MaxAge > 0:
-                // MaxAge was set in cookie: Value is seconds until expiration
-                c.Expires = time.Now().Add(time.Duration(c.MaxAge) * time.Second)
-        case c.MaxAge < 0:
-                // MaxAge was set and requires deletion of cookie:
-                // set expiration to "long ago"
-                c.Expires = time.Now().Add(-10 * time.Hour)
-        default:
-                // MaxAge was not set in response
-        }
-        c.MaxAge = 0
-
-        // use host from reguest if domain not set
-        if c.Domain == "" {
-                c.Domain = domain
-                return &c // assuming domain is valid
-        }
-        if c.Domain == "localhost" {
-                return &c
-        }
-
-        // make effective domain and prevent wildcards for tlds
-        if c.Domain[0] != '.' {
-                c.Domain = "." + c.Domain
-        }
-        n := strings.Count(c.Domain, ".")
-        if n < 2 {
-                return nil // ".org" is forbidden
-        }
-        if n == 2 && len(c.Domain) == 6 && strings.LastIndex(c.Domain, ".") == 3 {
-                // ".co.uk" is forbidden (bad luck for domains like o2.uk but browser·
-                // do it the same way)
-                return nil
-        }
-
-        // TODO: how to handle ip addresses insted of host/domain names?
-        // reject? disallow wildcards?  --> no wildcards
-        if isIP(domain) {
-                if isIP(c.Domain[1:]) && domain == c.Domain[1:] {
-                        return &c // valid: both IP and exact match
-                }
-                return nil
-        }
-        if isIP(c.Domain[1:]) {
-                return nil
-        }
-
-        // c.Domain now of the form .ibm.com or .www.company.org or even .test.int.company.net
-        if !strings.HasSuffix(c.Domain, domain) {
-                // okay: domain==www.company.net and c.Domain==.sso.company.net
-                // not okay : domain==www.company.net and c.Domain==.www.other.org
-                i := strings.LastIndex(domain, ".")
-                i = strings.LastIndex(domain[:i], ".")
-                domain = domain[i:] // works as n>=3
-                if !strings.HasSuffix(c.Domain, domain) {
-                        return nil
-                }
-        }
-
-        return &c
-}
-
-// isIP check if the given host is not a host name but an IP address.
-func isIP(host string) bool {
-        // TODO: maybe handle IPv6
-        r := strings.Split(host, ".")
-        if len(r) != 4 {
-                return false
-        }
-        is0to255 := func(s string) bool {
-                n, err := strconv.Atoi(s)
-                return err != nil || n < 0 || n > 255
-        }
-        return is0to255(r[0]) && is0to255(r[1]) && is0to255(r[2]) && is0to255(r[3]) // almost...
-}
-
-type CookieState int // used for qualifyCookie
-const (
-        CookieValid   CookieState = iota // include into request
-        CookieInvalid                    // do not include as some filed prohibit sending
-        CookieExpired                    // do not include, cookie is expired
-)
-
-// qualifyCookie checks if a cookie qualifies to be sent to the url.
-// The relevant parts of the url have to be provided as host, path and scheme.
-// The current time (as UTC().Seconds()) has to be provided as now.
-// If strict is true, than no wildcard domains in cookies are allowed:
-// I.e. the domain of the cookie must match the host exactly.
-func qualifyCookie(cookie *Cookie, host, path, scheme string, now time.Time, strict bool) CookieState {
-        if expired(cookie, now) {
-                return CookieExpired
-        }
-        if !cookieDomainMatch(host, cookie.Domain, strict) {
-                return CookieInvalid
-        }
-        if !cookiePathMatch(path, cookie.Path) {
-                return CookieInvalid
-        }
-        if cookie.HttpOnly && !(scheme == "http" || scheme == "https") {
-                return CookieInvalid
-        }
-        if cookie.Secure && scheme != "https" {
-                return CookieInvalid
-        }
-        return CookieValid
-}
-
-// hostname returns the hostname without port from the given URL u.
-func hostname(u *url.URL) string {
-        host := u.Host
-        if i := strings.Index(host, ":"); i != -1 {
-                host = host[:i]
-        }
-        return host
-}
-
-// expired checks if a normalized cookie is expired
-func expired(cookie *Cookie, now time.Time) bool {
-        return !cookie.Expires.IsZero() && cookie.Expires.Before(now)
-}
-
-// cookieDomainMatch checks if the requestHost matches the effective domain·
-// of the cookie cookieDomain.  All domains of the cookies in the jar are
-// assumed to be effective domains, i.e. the start with a dot ".".
-// Setting strictSameDomain to true will disable wildcard domains in
-// the cookies.
-func cookieDomainMatch(requestHost, cookieDomain string, strictSameDomain bool) bool {
-        if requestHost == cookieDomain[1:] {
-                return true // www.host.com = .www.host.com
-        }
-        if !strictSameDomain && strings.HasSuffix(requestHost, cookieDomain) {
-                return true // sso.host.com = .host.com
-        }
-        return false // all other cases
-}
-
-// pathMatch check if the the cookie with path cookiePath sould be sent to
-// a request with path requestPath:
-// Include cookie with Path="/some" in request to "/some",
-// "/some/path" as well as "/some/pathways" (TODO: check this case)·
-// but not in requests to "/other/path".
-func cookiePathMatch(requestPath, cookiePath string) bool {
-        return strings.HasPrefix(requestPath, cookiePath)
-}
-
-// TrivialJar implements a very simple CookieJar. TrivialJar is not thread-
-// or goroutine-safe and shows bad performance for large amounts of cookies.
-type TrivialJar struct {
-        cookies []*Cookie
-}
-
-// NewTrivialJar sets up a TrivialJar with an initial capacity for n cookies.
-func NewTrivialJar(n int) TrivialJar {
-        jar := TrivialJar{}
-        jar.cookies = make([]*Cookie, 0, n)
-        return jar
-}
-
-// Update updates all cookies in the jar.
-func (jar TrivialJar) Update(cookies []*Cookie, host string) {
-        for _, cookie := range cookies {
-                cookie = normalizeCookie(cookie, host)
-                for i, c := range jar.cookies {
-                        if c.Domain == cookie.Domain && c.Path == cookie.Path && c.Name == cookie.Name {
-                                jar.cookies[i] = cookie
-                                continue
-                        }
-                }
-                jar.cookies = append(jar.cookies, cookie)
-        }
-}
-
-// Select selects all cookies from jar to be sent to the URL u.
-func (jar TrivialJar) Select(u *url.URL) []*Cookie {
-        selection := make([]*Cookie, 0, 10)
-        now := time.Now()
-        host := hostname(u)
-
-        for _, cookie := range jar.cookies {
-                if qualifyCookie(cookie, host, u.Path, u.Scheme, now, false) != CookieValid {
-                        continue
-                }
-                // check if this cookie is new or more specific than an existing
-                replaced := false
-                for i, c := range selection {
-                        if c.Name != cookie.Name {
-                                continue
-                        }
-                        if len(cookie.Path) > len(c.Path) {
-                                // this one is more specific than the one we found allready
-                                selection[i] = cookie
-                                replaced = true
-                        }
-                }
-                if !replaced {
-                        selection = append(selection, cookie)
-                }
-        }
-        return selection
-}
-
-// SimpleCookieJar implements a simple cookie jar. It can be shared by different
-// goroutines.  It's unsutable for very large amounts of cookies.
-type SimpleCookieJar struct {
-        cookies []*Cookie    // list of all cookies
-        mutex   sync.Mutex   // mutex to prevent concurrent modification
-        expired map[int]bool // index of expired/deleted cookies
-}
-
-// NewSimpleCookieJar sets up a new empty cookie jar with initial capacity for n cookies.
-func NewSimpleCookieJar(n int) *SimpleCookieJar {
-        jar := &SimpleCookieJar{}
-        jar.cookies = make([]*Cookie, 0, n)
-        jar.expired = make(map[int]bool, 30)
-        return jar
-}
-
-// Find looks up the index of cookie in our cookie jar.
-// The lookup is based on an exact match of the (Name, Domain, Path) tripple.
-func (jar *SimpleCookieJar) find(domain, path, name string) (int, *Cookie) {
-        for i, c := range jar.cookies {
-                if c.Domain == domain && path == c.Path && name == c.Name {
-                        return i, c
-                }
-        }
-        return -1, nil
-}
-
-// Update add/update cookies in the jar.
-func (jar *SimpleCookieJar) Update(cookies []*Cookie, domain string) {
-        now := time.Now()
-        jar.mutex.Lock()
-        defer jar.mutex.Unlock()
-        for _, c := range cookies {
-                cookie := normalizeCookie(c, domain)
-                if cookie == nil {
-                        continue // bad domain
-                }
-                idx, _ := jar.find(cookie.Domain, cookie.Path, cookie.Name)
-                if expired(cookie, now) && idx != -1 {
-                        jar.expired[idx] = true
-                        continue
-                }
-
-                if idx == -1 { // new cookie
-                        jar.cookies = append(jar.cookies, cookie)
-                } else { // update
-                        jar.cookies[idx] = cookie
-                }
-        }
-        jar.cleanup()
-        return
-}
-
-// Select selects all cookies from jar which should be sent to the given URL u.
-func (jar *SimpleCookieJar) Select(u *url.URL) []*Cookie {
-        host := hostname(u)
-        now := time.Now()
-
-        // list of possible cookies
-        selection := make([]*Cookie, 0, 10)
-        jar.mutex.Lock()
-        defer jar.mutex.Unlock()
-        for idx, cookie := range jar.cookies {
-                if _, expired := jar.expired[idx]; expired {
-                        continue
-                }
-                if state := qualifyCookie(cookie, host, u.Path, u.Scheme, now, false); state == CookieInvalid {
-                        continue
-                } else if state == CookieExpired {
-                        jar.expired[idx] = true
-                        continue
-                }
-                replaced := false
-                for i, c := range selection {
-                        if c.Name != cookie.Name {
-                                continue
-                        }
-                        if len(cookie.Path) > len(c.Path) {
-                                // this one is more specific than the one we found allready
-                                selection[i] = cookie
-                                replaced = true
-                        }
-                }
-                if !replaced {
-                        selection = append(selection, cookie)
-                }
-        }
-        jar.cleanup()
-
-        return selection
-}
-
-// cleanup will remove all expired cookies from the jar (and clear the set of·
-// expired cookies) if more than 20 expired cookies are present. The jar must
-// be locked before calling this method.
-func (jar *SimpleCookieJar) cleanup() {
-        exp := len(jar.expired)
-        if exp < 20 {
-                return
-        }
-
-        n := len(jar.cookies) - 1
-        for i := 0; i < len(jar.cookies)-exp; i++ {
-                if _, expired := jar.expired[i]; expired {
-                        jar.cookies[i] = jar.cookies[n]
-                        n--
-                }
-        }
-
-        // clear set of expired cookies
-        jar.expired = make(map[int]bool, 30)
-        jar.cookies = jar.cookies[:n+1]
-}
+func (blackHoleJar) SetCookies(u *url.URL, cookies []*Cookie) {}
+func (blackHoleJar) Cookies(u *url.URL) []*Cookie             { return nil }