Class: Rage::Cookies

Inherits:
Object
  • Object
show all
Defined in:
lib/rage/cookies.rb

Overview

Cookies provide a convenient way to store small amounts of data on the client side that persists across requests. They are commonly used for session management, personalization, and tracking user preferences.

Rage cookies support both simple string-based cookies and encrypted cookies for sensitive data.

To use cookies, add the domain_name gem to your Gemfile:

bundle add domain_name

Additionally, if you need to use encrypted cookies, see Session for setup steps.

Usage

Basic Cookies

Read and write simple string values:

# Set a cookie
cookies[:user_name] = "Alice"

# Read a cookie
cookies[:user_name] # => "Alice"

# Delete a cookie
cookies.delete(:user_name)

Cookie Options

Set cookies with additional options for security and control:

cookies[:user_id] = {
  value: "12345",
  expires: 1.year.from_now,
  secure: true,
  httponly: true,
  same_site: :lax
}

Encrypted Cookies

Store sensitive data securely with automatic encryption:

# Set an encrypted cookie
cookies.encrypted[:api_token] = "secret-token"

# Read an encrypted cookie
cookies.encrypted[:api_token] # => "secret-token"

Permanent Cookies

Create cookies that expire 20 years from now:

cookies.permanent[:remember_token] = "token-value"

# Can be combined with encrypted
cookies.permanent.encrypted[:user_id] = current_user.id

Domain Configuration

Control which domains can access your cookies:

# Specific domain
cookies[:cross_domain] = { value: "data", domain: "example.com" }

# All subdomains
cookies[:shared] = { value: "data", domain: :all }

# Multiple allowed domains
cookies[:limited] = { value: "data", domain: ["app.example.com", "api.example.com"] }

See Also:

Defined Under Namespace

Classes: EncryptedJar, SimpleJar

Instance Method Summary collapse

Instance Method Details

#[](key) ⇒ String

Read a cookie.

Parameters:

  • key (Symbol)

Returns:

  • (String) 


116
117
118
119
 
# File 'lib/rage/cookies.rb', line 116

def [](key)
  value = request_cookies[key]
  @jar.load(value) if value
end

#[]=(key, value) ⇒ Object

Set a cookie.

Examples:

cookie[:user_id] = current_user.id
cookie[:user_id] = { value: current_user.id, httponly: true, secure: true }

Parameters:

  • key (Symbol)
  • value (String, Hash)

Options Hash (value):

  • :path (String)
  • :secure (Boolean)
  • :httponly (Boolean)
  • :same_site (nil, :none, :lax, :strict)
  • :expires (Time)
  • :domain (String, Array<String>, :all)
  • :value (String) 


176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/rage/cookies.rb', line 176

def []=(key, value)
  @headers.compare_by_identity

  unless value.is_a?(Hash)
    serialized_value = @jar.dump(value)
    @request_cookies[key] = serialized_value
    @headers[set_cookie_key(key)] = Rack::Utils.add_cookie_to_header(nil, key, { value: serialized_value, expires: @expires })
    return
  end

  if (domain = value[:domain])
    host = @env["HTTP_HOST"]

    _domain = if domain.is_a?(String)
      domain
    elsif domain == :all
      DomainName(host).domain
    elsif domain.is_a?(Array)
      host if domain.include?(host)
    end
  end

  serialized_value = @jar.dump(value[:value])
  cookie = Rack::Utils.add_cookie_to_header(nil, key, {
    path: value[:path],
    secure: value[:secure],
    expires: value[:expires] || @expires,
    httponly: value[:httponly],
    same_site: value[:same_site],
    value: serialized_value,
    domain: _domain
  })

  @request_cookies[key] = serialized_value
  @headers[set_cookie_key(key)] = cookie
end

#delete(key, path: "/", domain: nil) ⇒ Object

Delete a cookie.

Parameters:

  • key (Symbol)
  • path (String) (defaults to: "/")
  • domain (String) (defaults to: nil) 


133
134
135
136
137
138
139
140
 
# File 'lib/rage/cookies.rb', line 133

def delete(key, path: "/", domain: nil)
  @headers.compare_by_identity

  @request_cookies[key] = nil
  @headers[set_cookie_key(key)] = Rack::Utils.add_cookie_to_header(nil, key, {
    value: "", expires: Time.at(0), path: path, domain: domain
  })
end

#encrypted ⇒ Object

Returns a jar that’ll automatically encrypt cookie values before sending them to the client and will decrypt them for read. If the cookie was tampered with by the user (or a 3rd party), nil will be returned.

This jar requires that you set a suitable secret for the verification on your app’s secret_key_base.

Examples:

cookies.encrypted[:user_id] = current_user.id


149
150
151
 
# File 'lib/rage/cookies.rb', line 149

def encrypted
  dup.tap { |c| c.jar = EncryptedJar }
end

#inspect ⇒ Object 



213
214
215
216
217
218
219
220
221
222
 
# File 'lib/rage/cookies.rb', line 213

def inspect
  cookies = request_cookies.transform_values do |v|
    decoded = Base64.urlsafe_decode64(v) rescue nil
    is_encrypted = decoded&.start_with?(EncryptedJar::PADDING)

    is_encrypted ? "<encrypted>" : v
  end

  "#<#{self.class.name} @request_cookies=#{cookies.inspect}"
end

#permanent ⇒ Object

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

Examples:

cookies.permanent[:user_id] = current_user.id


157
158
159
 
# File 'lib/rage/cookies.rb', line 157

def permanent
  dup.tap { |c| c.expires = Date.today.next_year(20) }
end

#size ⇒ Integer

Get the number of cookies.

Returns:

  • (Integer) 


124
125
126
 
# File 'lib/rage/cookies.rb', line 124

def size
  request_cookies.count { |_, v| !v.nil? }
end