Class: CookieJar::Jar

### Home Classes Methods

### In Files

- lib/cookiejar/jar.rb

### Parent

Object

### Methods

- ::from_a
- ::json_create
- ::new
- #add_cookie
- #add_cookie_to_path
- #expire_cookies
- #find_domain
- #find_or_add_domain_for_cookie
- #gather_header_values
- #get_cookie_header
- #get_cookies
- #set_cookie
- #set_cookie2
- #set_cookies_from_headers
- #to_a
- #to_json
- #to_uri

### Class/Module Index

Quicksearch

- CookieJar
- CookieJar::Cookie
- CookieJar::CookieValidation
- CookieJar::CookieValidation::PATTERN
- CookieJar::InvalidCookieError
- CookieJar::Jar

No matching classes.

# CookieJar::Jar

A cookie store for client side usage.

- Enforces cookie validity rules

- Returns just the cookies valid for a given URI

- Handles expiration of cookies

- Allows for persistence of cookie data (with or without session)

### Public Class Methods

from_a(cookies) click to toggle source

Create a new Jar from an array of Cookie objects. Expired cookies will still be added to the archive, and conflicting cookies will be overwritten by the last cookie in the array.

@param [Array<Cookie>] cookies array of cookie objects @return [CookieJar] a new CookieJar instance

    # File lib/cookiejar/jar.rb, line 182
    def self.from_a cookies
      jar = new
      cookies.each do |cookie|
        jar.add_cookie cookie
      end
      jar
    end

json_create(o) click to toggle source

Create a new Jar from a JSON-backed hash

@param o [Hash] the expanded JSON object @return [CookieJar] a new CookieJar instance

    # File lib/cookiejar/jar.rb, line 163
    def self.json_create o
      if o.is_a? String
        o = JSON.parse(o)
      end
      if o.is_a? Hash
        o = o['cookies']
      end
      cookies = o.inject([]) do |result, cookie_json|
        result << (Cookie.json_create cookie_json)
      end
      self.from_a cookies
    end

new() click to toggle source

Create a new empty Jar

    # File lib/cookiejar/jar.rb, line 48
    def initialize
      @domains = {}
    end

### Public Instance Methods

add_cookie(cookie) click to toggle source

Add a pre-existing cookie object to the jar.

@param [Cookie] cookie a pre-existing cookie object @return [Cookie] the cookie added to the store

    # File lib/cookiejar/jar.rb, line 126
    def add_cookie cookie
      domain_paths = find_or_add_domain_for_cookie cookie
      add_cookie_to_path domain_paths, cookie
      cookie
    end

expire_cookies(session = false) click to toggle source

Look through the jar for any cookies which have passed their expiration date, or session cookies from a previous session

@param session [Boolean] whether session cookies should be expired,

    or just cookies past their expiration date.

    # File lib/cookiejar/jar.rb, line 195
    def expire_cookies session = false
      @domains.delete_if do |domain, paths|
        paths.delete_if do |path, cookies|
          cookies.delete_if do |cookie_name, cookie|
            cookie.expired? || (session && cookie.session?)
          end
          cookies.empty?
        end
        paths.empty?
      end
    end

get_cookie_header(request_uri, opts = { }) click to toggle source

Given a request URI, return a string Cookie header.Cookies will be in order per RFC 2965 - sorted by longest path length, but otherwise unordered.

@param [String, URI] request_uri the address the HTTP request will be

    sent to

@param [Hash] opts options controlling returned cookies @option opts [Boolean] :script (false) Cookies marked HTTP-only will be ignored

    if true

@return String value of the Cookie header which should be sent on the

    HTTP request

    # File lib/cookiejar/jar.rb, line 249
    def get_cookie_header request_uri, opts = { }
      cookies = get_cookies request_uri, opts
      version = 0
      ver = [[],[]]
      cookies.each do |cookie|
        ver[cookie.version] << cookie
      end
      if (ver[1].empty?)
        # can do a netscape-style cookie header, relish the opportunity
        cookies.map do |cookie|
          cookie.to_s
        end.join ";"
      else
        # build a RFC 2965-style cookie header. Split the cookies into
        # version 0 and 1 groups so that we can reuse the '$Version' header
        result = ''
        unless ver[0].empty?
          result << '$Version=0;'
          result << ver[0].map do |cookie|
            (cookie.to_s 1,false)
          end.join(';')
          # separate version 0 and 1 with a comma
          result << ','
        end
        result << '$Version=1;'
        ver[1].map do |cookie|
          result << (cookie.to_s 1,false)
        end
        result
      end
    end

get_cookies(request_uri, opts = { }) click to toggle source

Given a request URI, return a sorted list of Cookie objects. Cookies will be in order per RFC 2965 - sorted by longest path length, but otherwise unordered.

@param [String, URI] request_uri the address the HTTP request will be

    sent to

@param [Hash] opts options controlling returned cookies @option opts [Boolean] :script (false) Cookies marked HTTP-only will be ignored

    if true

@return [Array<Cookie>] cookies which should be sent in the HTTP request

    # File lib/cookiejar/jar.rb, line 217
    def get_cookies request_uri, opts = { }
      uri = to_uri request_uri
      hosts = Cookie.compute_search_domains uri

      results = []
      hosts.each do |host|
        domain = find_domain host
        domain.each do |path, cookies|
          if uri.path.start_with? path
            results += cookies.values.select do |cookie|
              cookie.should_send? uri, opts[:script]
            end
          end
        end
      end
      #Sort by path length, longest first
      results.sort do |lhs, rhs|
        rhs.path.length <=> lhs.path.length
      end
    end

set_cookie(request_uri, cookie_header_values) click to toggle source

Given a request URI and a literal Set-Cookie header value, attempt to add the cookie(s) to the cookie store.

@param [String, URI] request_uri the resource returning the header @param [String] cookie_header_value the contents of the Set-Cookie @return [Cookie] which was created and stored @raise [InvalidCookieError] if the cookie header did not validate

    # File lib/cookiejar/jar.rb, line 59
    def set_cookie request_uri, cookie_header_values
      cookie_header_values.split(/, (?=[\w]+=)/).each do |cookie_header_value|
        cookie = Cookie.from_set_cookie request_uri, cookie_header_value
        add_cookie cookie
      end
    end

set_cookie2(request_uri, cookie_header_value) click to toggle source

Given a request URI and a literal Set-Cookie2 header value, attempt to add the cookie to the cookie store.

@param [String, URI] request_uri the resource returning the header @param [String] cookie_header_value the contents of the Set-Cookie2 @return [Cookie] which was created and stored @raise [InvalidCookieError] if the cookie header did not validate

    # File lib/cookiejar/jar.rb, line 73
    def set_cookie2 request_uri, cookie_header_value
      cookie = Cookie.from_set_cookie2 request_uri, cookie_header_value
      add_cookie cookie
    end

set_cookies_from_headers(request_uri, http_headers) click to toggle source

Given a request URI and some HTTP headers, attempt to add the cookie(s) (from Set-Cookie or Set-Cookie2 headers) to the cookie store. If a cookie is defined (by equivalent name, domain, and path) via Set-Cookie and Set-Cookie2, the Set-Cookie version is ignored.

@param [String, URI] request_uri the resource returning the header @param [Hash>] http_headers a Hash

    which may have a key of "Set-Cookie" or "Set-Cookie2", and values of
    either strings or arrays of strings

@return [Array<Cookie>,nil] the cookies created, or nil if none found. @raise [InvalidCookieError] if one of the cookie headers contained

    invalid formatting or data

    # File lib/cookiejar/jar.rb, line 90
    def set_cookies_from_headers request_uri, http_headers
      set_cookie_key = http_headers.keys.detect { |k| /\ASet-Cookie\Z/.match k }
      cookies = gather_header_values http_headers[set_cookie_key] do |value|
        begin
          Cookie.from_set_cookie request_uri, value
        rescue InvalidCookieError
        end
      end

      set_cookie2_key = http_headers.keys.detect { |k| /\ASet-Cookie2\Z/.match k }
      cookies += gather_header_values(http_headers[set_cookie2_key]) do |value|
        begin
          Cookie.from_set_cookie2 request_uri, value
        rescue InvalidCookieError
        end
      end

      # build the list of cookies, using a Jar. Since Set-Cookie2 values
      # come second, they will replace the Set-Cookie versions.
      jar = Jar.new
      cookies.each do |cookie|
        jar.add_cookie cookie
      end
      cookies = jar.to_a

      # now add them all to our own store.
      cookies.each do |cookie|
        add_cookie cookie
      end
      cookies
    end

to_a() click to toggle source

Return an array of all cookie objects in the jar

@return [Array<Cookie>] all cookies. Includes any expired cookies which have not yet been removed with expire_cookies

    # File lib/cookiejar/jar.rb, line 136
    def to_a
      result = []
      @domains.values.each do |paths|
        paths.values.each do |cookies|
          cookies.values.inject result, :<<
        end
      end
      result
    end

to_json(*a) click to toggle source

Return a JSON 'object' for the various data values. Allows for persistence of the cookie information

@param [Array] a options controlling output JSON text

    (usually a State and a depth)

@return [String] JSON representation of object data

    # File lib/cookiejar/jar.rb, line 152
    def to_json *a
      {
        'json_class' => self.class.name,
        'cookies' => to_a.to_json(*a)
      }.to_json(*a)
    end

### Protected Instance Methods

add_cookie_to_path(paths, cookie) click to toggle source

    # File lib/cookiejar/jar.rb, line 307
    def add_cookie_to_path paths, cookie
      path_entry = (paths[cookie.path] ||= {})
      path_entry[cookie.name] = cookie
    end

find_domain(host) click to toggle source

    # File lib/cookiejar/jar.rb, line 299
    def find_domain host
      @domains[host] || {}
    end

find_or_add_domain_for_cookie(cookie) click to toggle source

    # File lib/cookiejar/jar.rb, line 303
    def find_or_add_domain_for_cookie cookie
      @domains[cookie.domain] ||= {}
    end

gather_header_values(http_header_value, &block) click to toggle source

    # File lib/cookiejar/jar.rb, line 283
    def gather_header_values http_header_value, &block
      result = []
      if http_header_value.is_a? Array
        http_header_value.each do |value|
          result << block.call(value)
        end
      elsif http_header_value.is_a? String
        result << block.call(http_header_value)
      end
      result.compact
    end

to_uri(request_uri) click to toggle source

    # File lib/cookiejar/jar.rb, line 295
    def to_uri request_uri
      (request_uri.is_a? URI)? request_uri : (URI.parse request_uri)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.