Class Hoodoo::Services::Session < Object

# File lib/hoodoo/services/services/session.rb, line 163
def initialize( options = {} )
  @created_at = Time.now.utc

  self.session_id         = options[ :session_id         ] || Hoodoo::UUID.generate()
  self.storage_engine     = options[ :storage_engine     ] || :memcached
  self.storage_host_uri   = options[ :storage_host_uri   ] || options[ :memcached_host ]
  self.caller_id          = options[ :caller_id          ]
  self.caller_version     = options[ :caller_version     ] || 0
  self.caller_fingerprint = options[ :caller_fingerprint ]
end

# File lib/hoodoo/services/services/session.rb, line 652
def augment_with_permissions_for( 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()
  additional_permissions = ( interface.additional_permissions() || {} )[ action ]

  return self if additional_permissions.nil?

  # Otherwise, duplicate the session and its permissions (or generate
  # defaults) and merge the additional permissions.

  local_session     = self.dup()
  local_permissions = self.permissions ? self.permissions.dup() : Hoodoo::Services::Permissions.new

  local_permissions.merge!( additional_permissions.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.permissions = local_permissions

  case local_session.save_to_store()
    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

# File lib/hoodoo/services/services/session.rb, line 478
def delete_from_store
  begin

    store  = get_store()
    result = store.delete( key: self.session_id )

    case result
      when true
        return :ok
      when false
        raise 'Unknown storage engine failure'
      else
        raise result
    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_store: Session delete - connection fault',
      exception.to_s
    )

    return :fail
  end

end

# File lib/hoodoo/services/services/session.rb, line 518
def expired?
  exp = self.expires_at()
  now = Time.now.utc

  return ! ( exp.nil? || now < exp )
end

# File lib/hoodoo/services/services/session.rb, line 574
def from_h!( hash )
  hash = Hoodoo::Utilities.stringify( hash )

  %w(

    session_id
    caller_id
    caller_version
    caller_identity_name
    caller_fingerprint

  ).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.permissions = Hoodoo::Services::Permissions.new( value ) unless value.nil?
end

# File lib/hoodoo/services/services/session.rb, line 73
def identity=( hash )
  @identity = OpenStruct.new( hash )
end

# File lib/hoodoo/services/services/session.rb, line 295
def load_from_store!( sid )
  begin
    store        = get_store()
    session_hash = store.get( key: sid, allow_throw: true )

    if session_hash.nil?
      return :not_found
    else
      self.from_h!( session_hash )
      return :outdated if self.expired?

      cv = load_caller_version_from_store( store, 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_store!: Session loading failed - connection fault or session corrupt',
      exception.to_s
    )

  end

  return :fail
end

# File lib/hoodoo/services/services/session.rb, line 403
def memcached_host
  Hoodoo::Services::Middleware.logger.warn(
    'Hoodoo::Services::Session#memcached_host is deprecated - use #storage_host_uri'
  )

  storage_host_uri()
end

# File lib/hoodoo/services/services/session.rb, line 421
def memcached_host=( uri )
  Hoodoo::Services::Middleware.logger.warn(
    'Hoodoo::Services::Session#memcached_host= is deprecated - use #storage_host_uri='
  )

  self.storage_host_uri = uri
end

# File lib/hoodoo/services/services/session.rb, line 195
def save_to_store
  if self.caller_id.nil?
    raise 'Hoodoo::Services::Session\#save_to_store: Cannot save this session as it has no assigned Caller UUID'
  end

  begin
    store = get_store()

    # Try to update the Caller version in the store using this
    # Session's data. If this fails, the Caller version is out of
    # date or we couldn't talk to the store. Either way, bail out.
    #
    # TL;DR: The 'update' call here is critical.
    #
    # This process refreshes the caller version information in the
    # transient store back-end with each new Session. If eventually the
    # Caller version is expired or evicted, Sessions would be immediately
    # invalidated and a recreation would result in the Caller version
    # being rewritten.
    #
    # What if the Caller goes out of date? An external service must gate
    # access to Caller resource changes and update the Caller version
    # itself if the Caller alters in a way that should invalidate
    # Sessions. This refreshes the lifetime on that item which normally
    # expires at a much greater TTL than sessions anyway and, if anyone
    # tries to use a Stale session after, the Caller version mismatch
    # will invalidate it so they'll need a new one.
    #
    # If a Caller version is created but somehow evicted before any of
    # the older existing Sessions (perhaps because Caller version data is
    # small but Session data is large) then attempts to read the Session
    # will fail; *loading* a Session requires the Caller version. The
    # Caller would have to create a new Session and this would by virtue
    # of the handling resource endpoint's service code acquire the new
    # Caller version data immediately then cause it to be re-asserted /
    # re-written by the code below.
    #
    result = update_caller_version_in_store( self.caller_id,
                                             self.caller_version,
                                             store )

    return result unless result.equal?( :ok )

    # Must set this before saving, even though the delay between
    # setting this value and the store actually saving the value
    # with a TTL will mean that the store expires the key slightly
    # *after* the time we record.

    @expires_at = ( ::Time.now + TTL ).utc()
    result      = store.set( key:              self.session_id,
                             payload:          self.to_h(),
                             maximum_lifespan: TTL )

    case result
      when true
        return :ok
      when false
        raise 'Unknown storage engine failure'
      else
        raise result
    end

  rescue => exception

    # Log error and return nil if the session can't be parsed
    #
    Hoodoo::Services::Middleware.logger.warn(
      'Hoodoo::Services::Session\#save_to_store: Session saving failed - connection fault or session corrupt',
      exception.to_s
    )

  end

  return :fail
end

# File lib/hoodoo/services/services/session.rb, line 97
def scoping=( hash )
  @scoping = OpenStruct.new( hash )
end

# File lib/hoodoo/services/services/session.rb, line 528
def to_h
  hash = {}

  %w(

    session_id
    caller_id
    caller_version
    caller_identity_name
    caller_fingerprint

  ).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 ] = Hoodoo::Utilities.standard_datetime( value ) 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

# File lib/hoodoo/services/services/session.rb, line 437
def update_caller_version_in_memcached( cid, cv, store = nil )
  unless store.nil?
    Hoodoo::Services::Middleware.logger.warn(
      'Hoodoo::Services::Session#update_caller_version_in_memcached is deprecated - use #update_caller_version_in_store'
    )

    # Inefficient - create a TransientStore configured for the normal
    # Memcached connection data, but get hold of its storage engine and
    # change that engine's client to the provided Dalli::Client instance.

    temp_store = Hoodoo::TransientStore.new(
      storage_engine:    :memcached,
      storage_host_uri:  self.memcached_host(),
      default_namespace: 'nz_co_loyalty_hoodoo_session_'
    )

    memcached_engine        = temp_store.storage_engine_instance()
    memcached_engine.client = store

    begin
      update_caller_version_in_store( cid, cv, temp_store )
    ensure
      temp_store.close()
    end

  else
    update_caller_version_in_store( cid, cv )

  end
end

# File lib/hoodoo/services/services/session.rb, line 365
def update_caller_version_in_store( cid, cv, store = nil )
  begin
    store        ||= get_store()
    cached_version = load_caller_version_from_store( store, cid )

    if cached_version != nil && cached_version > cv
      return :outdated
    elsif save_caller_version_to_store( store, 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_store: Client version update - connection fault or corrupt record',
      exception.to_s
    )

  end

  return :fail
end