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)

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) 


172
173
174
175
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
 
# File 'lib/rage/cookies.rb', line 172

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

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

    processed_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])
  Rack::Utils.set_cookie_header!(@headers, key, {
    **value,
    value: serialized_value,
    domain: processed_domain,
    expires: value[:expires] || @expires
  })
  @request_cookies[key] = serialized_value
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
 
# File 'lib/rage/cookies.rb', line 133

def delete(key, path: "/", domain: nil)
  @request_cookies[key] = nil
  Rack::Utils.delete_cookie_header!(@headers, key, { 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


145
146
147
 
# File 'lib/rage/cookies.rb', line 145

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

#inspect ⇒ Object 



202
203
204
205
206
207
208
209
210
211
 
# File 'lib/rage/cookies.rb', line 202

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


153
154
155
 
# File 'lib/rage/cookies.rb', line 153

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