Class: ActionDispatch::Cookies::CookieJar

Inherits:
Hash show all
Defined in:
actionpack/lib/action_dispatch/middleware/cookies.rb

Overview

:nodoc:

Direct Known Subclasses

PermanentCookieJar, SignedCookieJar

Constant Summary

DOMAIN_REGEXP =

This regular expression is used to split the levels of a domain. The top level domain can be any string without a period or *.*, **.* style TLDs like co.uk or com.au

www.example.co.uk gives: $1 => example $2 => co.uk

example.com gives: $1 => example $2 => com

lots.of.subdomains.example.local gives: $1 => example $2 => local

/([^.]*)\.([^.]*|..\...|...\...)$/

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from Hash

#as_json, #assert_valid_keys, #deep_merge, #deep_merge!, #diff, #encode_json, #except, #except!, #extract!, #extractable_options?, from_xml, #reverse_merge, #reverse_merge!, #slice, #slice!, #stringify_keys, #stringify_keys!, #symbolize_keys, #symbolize_keys!, #to_param, #to_xml, #with_indifferent_access

Constructor Details

- (CookieJar) initialize(secret = nil, host = nil)



107
108
109
110
111
112
113
114
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 107

def initialize(secret = nil, host = nil)
  @secret = secret
  @set_cookies = {}
  @delete_cookies = {}
  @host = host

  super()
end

Class Method Details

+ (Object) build(request)



98
99
100
101
102
103
104
105
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 98

def self.build(request)
  secret = request.env[TOKEN_KEY]
  host = request.host

  new(secret, host).tap do |hash|
    hash.update(request.cookies)
  end
end

Instance Method Details

- (Object) [](name)

Returns the value of the cookie by name, or nil if no such cookie exists.



117
118
119
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 117

def [](name)
  super(name.to_s)
end

- (Object) []=(key, options)

Sets the cookie named name. The second argument may be the very cookie value, or a hash of options as documented above.



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 132

def []=(key, options)
  if options.is_a?(Hash)
    options.symbolize_keys!
    value = options[:value]
  else
    value = options
    options = { :value => value }
  end

  value = super(key.to_s, value)

  handle_options(options)

  @set_cookies[key] = options
  @delete_cookies.delete(key)
  value
end

- (Object) delete(key, options = {})

Removes the cookie on the client machine by setting the value to an empty string and setting its expiration date into the past. Like []=, you can pass in an options hash to delete cookies with extra data such as a :path.



153
154
155
156
157
158
159
160
161
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 153

def delete(key, options = {})
  options.symbolize_keys!

  handle_options(options)

  value = super(key.to_s)
  @delete_cookies[key] = options
  value
end

- (Object) handle_options(options)

:nodoc:



121
122
123
124
125
126
127
128
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 121

def handle_options(options) #:nodoc:
  options[:path] ||= "/"

  if options[:domain] == :all
    @host =~ DOMAIN_REGEXP
    options[:domain] = ".#{$1}.#{$2}"
  end
end

- (Object) permanent

Returns a jar that'll automatically set the assigned cookies to have an expiration date 20 years from now. Example:

cookies.permanent[:prefers_open_id] = true
# => Set-Cookie: prefers_open_id=true; path=/; expires=Sun, 16-Dec-2029 03:24:16 GMT

This jar is only meant for writing. You'll read permanent cookies through the regular accessor.

This jar allows chaining with the signed jar as well, so you can set permanent, signed cookies. Examples:

cookies.permanent.signed[:remember_me] = current_user.id
# => Set-Cookie: remember_me=BAhU--848956038e692d7046deab32b7131856ab20e14e; path=/; expires=Sun, 16-Dec-2029 03:24:16 GMT


174
175
176
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 174

def permanent
  @permanent ||= PermanentCookieJar.new(self, @secret)
end

- (Object) signed

Returns a jar that'll automatically generate a signed representation of cookie value and verify it when reading from the cookie again. This is useful for creating cookies with values that the user is not supposed to change. If a signed cookie was tampered with by the user (or a 3rd party), an ActiveSupport::MessageVerifier::InvalidSignature exception will be raised.

This jar requires that you set a suitable secret for the verification on your app's config.secret_token.

Example:

cookies.signed[:discount] = 45
# => Set-Cookie: discount=BAhpMg==--2c1c6906c90a3bc4fd54a51ffb41dffa4bf6b5f7; path=/

cookies.signed[:discount] # => 45


191
192
193
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 191

def signed
  @signed ||= SignedCookieJar.new(self, @secret)
end

- (Object) write(headers)



195
196
197
198
# File 'actionpack/lib/action_dispatch/middleware/cookies.rb', line 195

def write(headers)
  @set_cookies.each { |k, v| ::Rack::Utils.set_cookie_header!(headers, k, v) }
  @delete_cookies.each { |k, v| ::Rack::Utils.delete_cookie_header!(headers, k, v) }
end