Object
ID sets up a basic framework for implementing an id based sessioning service. Cookies sent to the client for maintaining sessions will only contain an id reference. Only # and # are required to be overwritten.
All parameters are optional.
:key determines the name of the cookie, by default it is ‘rack.session‘
:path, :domain, :expire_after, :secure, and :httponly set the related cookie options as by Rack::Response#add_cookie
:skip will not a set a cookie in the response nor update the session state
:defer will not set a cookie in the response but still update the session state if it is used with a backend
:renew (implementation dependent) will prompt the generation of a new session id, and migration of data to be referenced at the new id. If :defer is set, it will be overridden and the cookie will be set.
:sidbits sets the number of bits in length that a generated session id will be.
These options can be set on a per request basis, at the location of env. Additionally the id of the session can be found within the options hash at the key :id. It is highly not recommended to change its value.
Is Rack::Utils::Context compatible.
Not included by default; you must require ‘rack/session/abstract/id’ to use.
# File lib/rack/session/abstract/id.rb, line 191 191: def initialize(app, options={}) 192: @app = app 193: @default_options = self.class::DEFAULT_OPTIONS.merge(options) 194: @key = @default_options.delete(:key) 195: @cookie_only = @default_options.delete(:cookie_only) 196: initialize_sid 197: end
Acquires the session from the environment and the session id from the session options and passes them to #. If successful and the :defer option is not true, a cookie will be added to the response with the session’s id.
# File lib/rack/session/abstract/id.rb, line 307 307: def commit_session(env, status, headers, body) 308: session = env['rack.session'] 309: options = env['rack.session.options'] 310: 311: if options[:drop] || options[:renew] 312: session_id = destroy_session(env, options[:id] || generate_sid, options) 313: return [status, headers, body] unless session_id 314: end 315: 316: return [status, headers, body] unless commit_session?(env, session, options) 317: 318: session.send(:load!) unless loaded_session?(session) 319: session = session.to_hash 320: session_id ||= options[:id] || generate_sid 321: 322: if not data = set_session(env, session_id, session, options) 323: env["rack.errors"].puts("Warning! #{self.class.name} failed to save session. Content dropped.") 324: elsif options[:defer] and not options[:renew] 325: env["rack.errors"].puts("Defering cookie for #{session_id}") if $VERBOSE 326: else 327: cookie = Hash.new 328: cookie[:value] = data 329: cookie[:expires] = Time.now + options[:expire_after] if options[:expire_after] 330: set_cookie(env, headers, cookie.merge!(options)) 331: end 332: 333: [status, headers, body] 334: end
Session should be commited if it was loaded, any of specific options like :renew, :drop or :expire_after was given and the security permissions match. Skips if skip is given.
# File lib/rack/session/abstract/id.rb, line 275 275: def commit_session?(env, session, options) 276: if options[:skip] 277: false 278: else 279: has_session = loaded_session?(session) || forced_session_update?(session, options) 280: has_session && security_matches?(env, options) 281: end 282: end
Returns the current session id from the OptionsHash.
# File lib/rack/session/abstract/id.rb, line 261 261: def current_session_id(env) 262: env[ENV_SESSION_OPTIONS_KEY][:id] 263: end
All thread safety and session destroy proceedures should occur here. Should return a new session id or nil if options[:drop]
# File lib/rack/session/abstract/id.rb, line 366 366: def destroy_session(env, sid, options) 367: raise '#destroy_session not implemented' 368: end
Extract session id from request object.
# File lib/rack/session/abstract/id.rb, line 252 252: def extract_session_id(env) 253: request = Rack::Request.new(env) 254: sid = request.cookies[@key] 255: sid ||= request.params[@key] unless @cookie_only 256: sid 257: end
# File lib/rack/session/abstract/id.rb, line 292 292: def force_options?(options) 293: options.values_at(:renew, :drop, :defer, :expire_after).any? 294: end
# File lib/rack/session/abstract/id.rb, line 288 288: def forced_session_update?(session, options) 289: force_options?(options) && session && !session.empty? 290: end
Generate a new session id using Ruby #. The size of the session id is controlled by the :sidbits option. Monkey patch this to use custom methods for session id generation.
# File lib/rack/session/abstract/id.rb, line 221 221: def generate_sid(secure = @sid_secure) 222: if secure 223: SecureRandom.hex(@sid_length) 224: else 225: "%0#{@sid_length}x" % Kernel.rand(2**@sidbits - 1) 226: end 227: rescue NotImplementedError 228: generate_sid(false) 229: end
All thread safety and session retrival proceedures should occur here. Should return [session_id, session]. If nil is provided as the session id, generation of a new valid id should occur within.
# File lib/rack/session/abstract/id.rb, line 351 351: def get_session(env, sid) 352: raise '#get_session not implemented.' 353: end
# File lib/rack/session/abstract/id.rb, line 211 211: def initialize_sid 212: @sidbits = @default_options[:sidbits] 213: @sid_secure = @default_options[:secure_random] 214: @sid_length = @sidbits / 4 215: end
Extracts the session id from provided cookies and passes it and the environment to #.
# File lib/rack/session/abstract/id.rb, line 244 244: def load_session(env) 245: sid = current_session_id(env) 246: sid, session = get_session(env, sid) 247: [sid, session || {}] 248: end
# File lib/rack/session/abstract/id.rb, line 284 284: def loaded_session?(session) 285: !session.is_a?(SessionHash) || session.loaded? 286: end
Sets the lazy session at ‘rack.session’ and places options and session metadata into ‘rack.session.options’.
# File lib/rack/session/abstract/id.rb, line 234 234: def prepare_session(env) 235: session_was = env[ENV_SESSION_KEY] 236: env[ENV_SESSION_KEY] = SessionHash.new(self, env) 237: env[ENV_SESSION_OPTIONS_KEY] = OptionsHash.new(self, env, @default_options) 238: env[ENV_SESSION_KEY].merge! session_was if session_was 239: end
# File lib/rack/session/abstract/id.rb, line 296 296: def security_matches?(env, options) 297: return true unless options[:secure] 298: request = Rack::Request.new(env) 299: request.ssl? 300: end
Check if the session exists or not.
# File lib/rack/session/abstract/id.rb, line 267 267: def session_exists?(env) 268: value = current_session_id(env) 269: value && !value.empty? 270: end
All thread safety and session storage proceedures should occur here. Should return true or false dependant on whether or not the session was saved or not.
# File lib/rack/session/abstract/id.rb, line 359 359: def set_session(env, sid, session, options) 360: raise '#set_session not implemented.' 361: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.