Class: GlobalSession::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/global_session/configuration.rb

Overview

Central point of access for GlobalSession configuration information. This is mostly a very thin wrapper around the serialized hash written to the YAML config file.

The configuration is stored as a set of nested hashes and accessed by the code using hash lookup; for example, we might ask for Configuration[‘domain’] if we wanted to know which domain the cookie should be set for.

The following settings are supported:

  • attributes

    * signed
* insecure

  • ephemeral

  • timeout

  • renew

  • authority (optional - inferred from presence of private key file)

  • trust (optional - inferred from presence/name of public key files)

  • directory

  • cookie

    * version
* name
* domain

Config Environments

The operational environment of global_session defines which section of the configuration file it gets its settings from. When used with a web app, the environment should be set to the same environment as the web app. (If using Rails integration, this happens for you automatically.)

Environment-Specific Settings

The top level of keys in the configuration hash are special; they provide different sections of settings that apply in different environments. For instance, a Rails application might have one set of settings that apply in the development environment; these would appear under Configuration. Another set of settings would apply in the production environment and would appear under Configuration.

Common Settings

In addition to having one section for each operating environment, the configuration file can specify a ‘common’ section for settings that apply

Lookup Mechanism

When the code asks for Configuration, we first check whether the current environment’s config section has a value for foo. If one is found, we return that.

If no environment-specific setting is found, we check the ‘common’ section and return the value found there.

Config File Location

The name and location of the config file depend on the Web framework with which you are integrating; see GlobalSession::Rails for more information.

Instance Method Summary collapse

Constructor Details

#initialize(config, environment) ⇒ Configuration

Create a new Configuration object

Parameters

config(String|Hash)

Absolute filesystem path to the configuration file, or Hash containing configuration

environment(String)

Config file section from which to read settings

Raise

MissingConfiguration

if config file is missing or unreadable

TypeError

if config file does not contain a YAML-serialized Hash



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/global_session/configuration.rb', line 97

def initialize(config, environment)
  if config.is_a?(Hash)
    @config = config
  elsif File.file?(config)
    yaml = ERB.new(File.read(config)).result
    data = YAML.load(yaml)
    unless data.is_a?(Hash)
      raise TypeError, "Configuration file #{File.basename(config)} must contain a hash as its top-level element"
    end
    @config = data
  else
    raise MissingConfiguration, "Missing or unreadable configuration file #{config}"
  end

  @environment = environment
  validate
end

Instance Method Details

#[](key) ⇒ Object

Reader for configuration elements. The reader first checks the current environment’s settings section for the named value; if not found, it checks the common settings section.

Parameters

key(String)

Name of configuration element to retrieve

Return

value(String)

the value of the configuration element



124
125
126
 
# File 'lib/global_session/configuration.rb', line 124

def [](key)
  get(key, true)
end

#[]=(key, value = {}) ⇒ Object

Writer for configuration elements. Writes to an environment-specific stanza if one is present, else writes to the common stanza. DOES NOT OVERWRITE the key’s value if it already has one!

Parameters:

  • key (String)
  • optional (Object) —

    the value to write, or empty-hash as a default



133
134
135
136
137
138
139
140
141
 
# File 'lib/global_session/configuration.rb', line 133

def []=(key, value={})
  if @config.has_key?(@environment)
    @config[@environment][key] ||= value
  else
    @config['common'][key] ||= value
  end
rescue NoMethodError
  raise MissingConfiguration, "Configuration key '#{key}' not found"
end

#has_key?(k) ⇒ Boolean Also known as: key?

Determine whether a given configuration key was specified.

Returns:

  • (Boolean) —

    true if the key is present in the common or per-environment stanzas



146
147
148
 
# File 'lib/global_session/configuration.rb', line 146

def has_key?(k)
  (@config.has_key?(@environment) && @config[@environment].has_key?(k)) || @config['common'].has_key?(k)
end

#inspect ⇒ Object

Returns a representation of the object suitable for printing to the console.

Returns:

  • a representation of the object suitable for printing to the console



80
81
82
 
# File 'lib/global_session/configuration.rb', line 80

def inspect
  "<#{self.class.name} @environment=#{@environment.inspect}>"
end

#to_hash ⇒ Object 



84
85
86
 
# File 'lib/global_session/configuration.rb', line 84

def to_hash
  @config.dup
end

#validate ⇒ Object

:nodoc



152
153
154
 
# File 'lib/global_session/configuration.rb', line 152

def validate # :nodoc
  ['attributes/signed', 'cookie/name', 'timeout'].each {|k| validate_presence_of k}
end