Class: Hoodoo::Services::Session
- Inherits:
-
Object
- Object
- Hoodoo::Services::Session
- Defined in:
- lib/hoodoo/services/services/session.rb
Overview
A container for functionality related to a context session.
Defined Under Namespace
Classes: MockDalliClient
Constant Summary collapse
- TTL =
Time To Live: Number of seconds for which a session remains valid after being saved. Only applicable from the save time onwards in stores that support TTL such as Memcached - see #save_to_memcached.
172800
Instance Attribute Summary collapse
-
#caller_id ⇒ Object
A Session must always refer to a Caller instance by UUID.
-
#caller_identity_name ⇒ Object
An optional property of a session is the Caller’s “identity name”, a generic way to refer to this Caller which will appear in logs.
-
#caller_version ⇒ Object
Callers can change; if so, related sessions must be invalidated.
-
#created_at ⇒ Object
readonly
The creation date of this session instance as a Time instance in UTC.
-
#expires_at ⇒ Object
readonly
The expiry date for this session - the session should be considered expired at or after this date.
-
#identity ⇒ Object
An OpenStruct instance with session-creator defined key/value pairs that define the identity of the session holder.
-
#memcached_host ⇒ Object
Connection IP address/port String for Memcached.
-
#permissions ⇒ Object
A Hoodoo::Services::Permissions instance.
-
#scoping ⇒ Object
An OpenStruct instance with session-creator defined values that describe the scoping, that is, visbility of data, for the session.
-
#session_id ⇒ Object
A Session must have its own UUID.
Instance Method Summary collapse
-
#augment_with_permissions_for(interaction) ⇒ Object
Speciality interface usually only called by the middleware, or components closely related to the middleware.
-
#delete_from_memcached ⇒ Object
Delete this session from Memcached.
-
#expired? ⇒ Boolean
Has this session expired? Only valid if an expiry date is set; see #expires_at.
-
#from_h!(hash) ⇒ Object
Load session parameters from a given Hash, of the form set by #to_h.
-
#initialize(options = {}) ⇒ Session
constructor
Create a new instance.
-
#load_from_memcached!(sid) ⇒ Object
Load session data into this instance, overwriting instance values if the session is found.
-
#save_to_memcached ⇒ Object
Save this session to Memcached, in a manner that will allow it to be loaded by #load_from_memcached! later.
-
#to_h ⇒ Object
Represent this session’s data as a Hash, for uses such as storage in Memcached or loading into another session instance.
-
#update_caller_version_in_memcached(cid, cv, mclient = nil) ⇒ Object
Update the version of a given Caller in Memcached.
Constructor Details
#initialize(options = {}) ⇒ Session
Create a new instance.
options
-
Optional Hash of options, described below.
Options are:
session_id
-
UUID of this session. If unset, a new UUID is generated for you. You can read the UUID with the #session_id accessor method.
caller_id
-
UUID of the Caller instance associated with this session. This can be set either now or later, but the session cannot be saved without it.
caller_version
-
Version of the Caller instance; defaults to zero.
memcached_host
-
Host for Memcached connections; required if you want to use the #load_from_memcached! or #save_to_memcached methods.
144 145 146 147 148 149 150 151 |
# File 'lib/hoodoo/services/services/session.rb', line 144 def initialize( = {} ) @created_at = Time.now.utc self.session_id = [ :session_id ] || Hoodoo::UUID.generate() self.memcached_host = [ :memcached_host ] self.caller_id = [ :caller_id ] self.caller_version = [ :caller_version ] || 0 end |
Instance Attribute Details
#caller_id ⇒ Object
A Session must always refer to a Caller instance by UUID.
33 34 35 |
# File 'lib/hoodoo/services/services/session.rb', line 33 def caller_id @caller_id end |
#caller_identity_name ⇒ Object
An optional property of a session is the Caller’s “identity name”, a generic way to refer to this Caller which will appear in logs. The use is up to the session creator, in combination with whatever logging engine is in use; if it ascribes meaning to the identity name, then the session creator must ensure it comforms.
41 42 43 |
# File 'lib/hoodoo/services/services/session.rb', line 41 def caller_identity_name @caller_identity_name end |
#caller_version ⇒ Object
Callers can change; if so, related sessions must be invalidated. This must be achieved by keeping a version count on the Caller. A session is associated with a particular Caller version and if the version changes, associated sessions are flushed.
If you change a Caller version in a Session, you really should call #save_to_memcached as soon as possible afterwards so that the change gets recognised in Memcached.
52 53 54 |
# File 'lib/hoodoo/services/services/session.rb', line 52 def caller_version @caller_version end |
#created_at ⇒ Object (readonly)
The creation date of this session instance as a Time instance in UTC.
98 99 100 |
# File 'lib/hoodoo/services/services/session.rb', line 98 def created_at @created_at end |
#expires_at ⇒ Object (readonly)
The expiry date for this session - the session should be considered expired at or after this date. Some session stores may support automatic expiry of session data, but there may be a small window between the expiry date passing and the store expiring the data; so always check the expiry.
Only set when the session is saved (or loaded from a representation that includes an existing expiry date). See e.g.:
-
#save_to_memcached
The value is a Time instance in UTC. If nil
, the session has not yet been saved.
114 115 116 |
# File 'lib/hoodoo/services/services/session.rb', line 114 def expires_at @expires_at end |
#identity ⇒ Object
An OpenStruct instance with session-creator defined key/value pairs that define the identity of the session holder. This is usually related to a Caller resource instance - see also Hoodoo::Data::Resources::Caller - and will often contain a Caller resource instance’s UUID, amongst other data.
The object describes “who the session’s owner is”.
62 63 64 |
# File 'lib/hoodoo/services/services/session.rb', line 62 def identity @identity end |
#memcached_host ⇒ Object
Connection IP address/port String for Memcached.
If you are using Memcached for a session store, you can set the Memcached connection host either through this accessor, or via the object’s constructor.
122 123 124 |
# File 'lib/hoodoo/services/services/session.rb', line 122 def memcached_host @memcached_host end |
#permissions ⇒ Object
A Hoodoo::Services::Permissions instance.
The instance describes “what the session is allowed to do”.
75 76 77 |
# File 'lib/hoodoo/services/services/session.rb', line 75 def @permissions end |
#scoping ⇒ Object
An OpenStruct instance with session-creator defined values that describe the scoping, that is, visbility of data, for the session. Its contents relate to service resource interface descriptions (see the DSL for Hoodoo::Services::Interface) and may be partially or entirely supported by the ActiveRecord finder extensions in Hoodoo::ActiveRecord::Finder.
The object describes the “data that the session can ‘see’”.
86 87 88 |
# File 'lib/hoodoo/services/services/session.rb', line 86 def scoping @scoping end |
#session_id ⇒ Object
A Session must have its own UUID.
29 30 31 |
# File 'lib/hoodoo/services/services/session.rb', line 29 def session_id @session_id end |
Instance Method Details
#augment_with_permissions_for(interaction) ⇒ Object
Speciality interface usually only called by the middleware, or components closely related to the middleware.
Takes this session and creates a copy for an inter-resource call which adds any additional parameters that the calling interface says it needs in order to complete the currently handled action.
Through calling this method, the middleware implements the access permission functionality described by Hoodoo::Services::Interface#additional_permissions_for.
interaction
-
Hoodoo::Services::Middleware::Interaction instance describing the current interaction. This is for the request that a resource implementation *is handling* at the point it wants to make an inter-resource call
-
it is not data related to the target of that
call.
-
Returns:
-
Hoodoo::Services::Session instance if everything works OK; this may be the same as, or different from, the input session depending on whether or not there were any permissions that needed adding.
-
false
if the session can’t be saved due to a mismatched caller version - the session must have become invalid during handling.
If the augmented session cannot be saved due to a Memcached problem, an exception is raised and the generic handler will turn this into a 500 response for the caller. At this time, we really can’t do much better than that since failure to save the augmented session means the inter-resource call cannot proceed; it’s an internal fault.
501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 |
# File 'lib/hoodoo/services/services/session.rb', line 501 def ( interaction ) # Set up some convenience variables interface = interaction.target_interface action = interaction.requested_action # If there are no additional permissions for this action, just return # the current session back again. action = action.to_s() = ( interface.() || {} )[ action ] return self if .nil? # Otherwise, duplicate the session and its permissions (or generate # defaults) and merge the additional permissions. local_session = self.dup() = self. ? self..dup() : Hoodoo::Services::Permissions.new .merge!( .to_h() ) # Make sure the new session has its own ID and set the updated # permissions. Then try to save it and return the result. local_session.session_id = Hoodoo::UUID.generate() local_session. = case local_session.save_to_memcached() when :ok return local_session when :outdated # Caller version mismatch; original session is now outdated and invalid return false else # Couldn't save it raise "Unable to create interim session for inter-resource call from #{ interface.resource } / #{ action }" end end |
#delete_from_memcached ⇒ Object
Delete this session from Memcached. The Session object is not modified.
Returns a symbol:
-
:ok
: The Session was deleted from Memcached successfully. -
:not_found
: This session was not found in Memcached. -
:fail
: The session data could not be deleted (Memcached problem).
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 |
# File 'lib/hoodoo/services/services/session.rb', line 337 def delete_from_memcached begin mclient = self.class.connect_to_memcached( self.memcached_host() ) if mclient.delete( self.session_id ) return :ok else return :not_found end rescue => exception # Log error and return nil if the session can't be parsed # Hoodoo::Services::Middleware.logger.warn( 'Hoodoo::Services::Session\#delete_from_memcached: Session delete - connection fault', exception.to_s ) return :fail end end |
#expired? ⇒ Boolean
Has this session expired? Only valid if an expiry date is set; see #expires_at.
Returns true
if the session has expired, or false
if it has either not expired, or has no expiry date set yet.
368 369 370 371 372 373 |
# File 'lib/hoodoo/services/services/session.rb', line 368 def expired? exp = self.expires_at() now = Time.now.utc return ! ( exp.nil? || now < exp ) end |
#from_h!(hash) ⇒ Object
Load session parameters from a given Hash, of the form set by #to_h.
If appropriate Hash keys are present, will set any or all of #session_id, #identity, #scoping and #permissions.
424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 |
# File 'lib/hoodoo/services/services/session.rb', line 424 def from_h!( hash ) hash = Hoodoo::Utilities.stringify( hash ) %w( session_id caller_id caller_version caller_identity_name ).each do | property | value = hash[ property ] self.send( "#{ property }=", value ) unless value.nil? end %w( created_at expires_at ).each do | property | if hash.has_key?( property ) begin instance_variable_set( "@#{ property }", Time.parse( hash[ property ] ).utc() ) rescue => e # Invalid time given; keep existing date end end end %w( identity scoping ).each do | property | value = hash[ property ] self.send( "#{ property }=", OpenStruct.new( value ) ) unless value.nil? end value = hash[ 'permissions' ] self. = Hoodoo::Services::Permissions.new( value ) unless value.nil? end |
#load_from_memcached!(sid) ⇒ Object
Load session data into this instance, overwriting instance values if the session is found. Raises an exception if there is a problem connecting to Memcached. A Memcached connection host must have been set through the constructor or #memcached_host accessor first.
sid
-
The Session UUID to look up.
Returns a symbol:
-
:ok
: The session data was loaded OK and is valid. -
:outdated
: The session data was loaded, but is outdated; either the session has expired, or its Caller version mismatches the associated stored Caller version in Memcached. -
:not_found
: The session was not found. -
:fail
: The session data could not be loaded (Memcached problem).
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 |
# File 'lib/hoodoo/services/services/session.rb', line 236 def load_from_memcached!( sid ) begin mclient = self.class.connect_to_memcached( self.memcached_host() ) session_hash = mclient.get( sid ) if session_hash.nil? return :not_found else self.from_h!( session_hash ) return :outdated if self.expired? cv = load_caller_version_from_memcached( mclient, self.caller_id ) if cv == nil || cv > self.caller_version return :outdated else return :ok end end rescue => exception # Log error and return nil if the session can't be parsed # Hoodoo::Services::Middleware.logger.warn( 'Hoodoo::Services::Session\#load_from_memcached!: Session loading failed - connection fault or session corrupt', exception.to_s ) end return :fail end |
#save_to_memcached ⇒ Object
Save this session to Memcached, in a manner that will allow it to be loaded by #load_from_memcached! later.
A session can only be saved if it has a Caller ID - see #caller_id= or the options hash passed to the constructor.
The Hoodoo::Services::Session::TTL constant determines how long the key lives in Memcached.
Returns a symbol:
-
:ok
: The session data was saved OK and is valid. There was either a Caller record with an earlier or matching value in Memcached, or no preexisting record of the Caller. -
:outdated
: The session data could not be saved because an existing Caller record was found in Memcached with a newer version than ‘this’ session, implying that the session is already outdated. -
:fail
: The session data could not be saved (Memcached problem).
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 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 |
# File 'lib/hoodoo/services/services/session.rb', line 174 def save_to_memcached if self.caller_id.nil? raise 'Hoodoo::Services::Session\#save_to_memcached: Cannot save this session as it has no assigned Caller UUID' end begin mclient = self.class.connect_to_memcached( self.memcached_host() ) # Try to update the Caller version in Memcached using this # Session's data. If this fails, the Caller version is out of # date or we couldn't talk to Memcached. Either way, bail out. result = update_caller_version_in_memcached( self.caller_id, self.caller_version, mclient ) return result unless result.equal?( :ok ) # Must set this before saving, even though the delay between # setting this value and Memcached actually saving the value # with a TTL will mean that Memcached expires the key slightly # *after* the time we record. @expires_at = ( ::Time.now + TTL ).utc() return :ok if mclient.set( self.session_id, self.to_h(), TTL ) rescue => exception # Log error and return nil if the session can't be parsed # Hoodoo::Services::Middleware.logger.warn( 'Hoodoo::Services::Session\#save_to_memcached: Session saving failed - connection fault or session corrupt', exception.to_s ) end return :fail end |
#to_h ⇒ Object
Represent this session’s data as a Hash, for uses such as storage in Memcached or loading into another session instance. See also #from_h!.
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 |
# File 'lib/hoodoo/services/services/session.rb', line 379 def to_h hash = {} %w( session_id caller_id caller_version caller_identity_name ).each do | property | value = self.send( property ) hash[ property ] = value unless value.nil? end %w( created_at expires_at ).each do | property | value = self.send( property ) hash[ property ] = value.iso8601() unless value.nil? end %w( identity scoping permissions ).each do | property | value = self.send( property ) hash[ property ] = Hoodoo::Utilities.stringify( value.to_h() ) unless value.nil? end return hash end |
#update_caller_version_in_memcached(cid, cv, mclient = nil) ⇒ Object
Update the version of a given Caller in Memcached. This is done automatically when Sessions are saved to Memcached, but if external code alters any Callers independently, it MUST call here to keep Memcached records up to date.
If no cached version is in Memcached for the Caller, the method assumes it is being called for the first time for that Caller and writes the version it has to hand, rather than considering it an error condition.
cid
-
Caller UUID of the Caller record to update.
cv
-
New version to store (an Integer).
mclient
-
Optional Dalli::Client instance to use for talking to Memcached. If omitted, a connection is established for you. This is mostly an optimisation parameter, used by code which already has established a connection and wants to avoid creating another unnecessarily.
Returns a Symbol:
-
:ok
: The Caller record was updated successfully. -
:outdated
: The Caller was already present in Memcached with a _higher version_ than the one you wanted to save. Your own local Caller data must therefore already be out of date. -
:fail
: The Caller could not be updated (Memcached problem).
300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 |
# File 'lib/hoodoo/services/services/session.rb', line 300 def update_caller_version_in_memcached( cid, cv, mclient = nil ) begin mclient ||= self.class.connect_to_memcached( self.memcached_host() ) cached_version = load_caller_version_from_memcached( mclient, cid ) if cached_version != nil && cached_version > cv return :outdated elsif save_caller_version_to_memcached( mclient, cid, cv ) == true return :ok end rescue => exception # Log error and return nil if the session can't be parsed # Hoodoo::Services::Middleware.logger.warn( 'Hoodoo::Services::Session\#update_caller_version_in_memcached: Client version update - connection fault or corrupt record', exception.to_s ) end return :fail end |