ncs_navigator_configuration 0.0.1

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+
+.yardoc
+doc

data/.yardopts

@@ -0,0 +1,5 @@
+--no-private
+--markup markdown
+--hide-void-return
+--files CHANGELOG.md,sample_configuration.ini
+--readme README.md

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+NCS Navigator Configuration gem history
+=======================================
+
+0.0.1
+-----
+
+- Initial version based on configuration elements from Staff Portal
+  and MDES Warehouse.

data/Gemfile

@@ -0,0 +1,9 @@
+source :rubygems
+
+gemspec
+
+group :development do
+  # For yard's markdown support
+  platforms :jruby             do gem 'maruku' end
+  platforms :ruby_18, :ruby_19 do gem 'rdiscount' end
+end

data/README.md

@@ -0,0 +1,40 @@
+NCS Navigator Common Configuration
+==================================
+
+This gem provides common configuration services to the various
+applications that make up NCS Navigator. It's not generally useful
+outside of that suite.
+
+Use
+---
+
+{NcsNavigator::Configuration} defines the common configuration
+attributes for applications in the NCS Navigator suite. It also
+provides helpers (e.g.,
+{NcsNavigator::Configuration#action_mailer_smtp_settings} for applying
+the configuration to some utility libraries.
+
+{NcsNavigator.configuration} provides a global access point for an
+instance of `NcsNavigator::Configuration`. It can be explicitly set,
+but more commonly it is initialized from a configuration file named
+`/etc/nubic/ncs/navigator.ini` (see next section) on first access. If
+the INI file is changed, you'll need to set
+`NcsNavigator.configuration` to `nil` to have the changes reflected in
+the global instance.
+
+Configuration
+-------------
+
+An instance of {NcsNavigator::Configuration} may be initialized from
+an INI file or by passing a Hash to its constructor.  The INI file
+should match {file:sample_configuration.ini} available alongside this
+file. The Hash should have two levels, the top level matching the INI
+file's sections and the second level the keys.
+
+In addition to the typed configuration properties available on
+`NcsNavigator::Configuration`, there are also three
+application-specific accessors: {#staff_portal, #core, and
+#psc}. These provide untyped direct access to the configuration
+properties in the respective sections of the INI file, allowing
+applications to define their own additional configuration properties
+without modifying this library.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "spec/**/*_spec.rb"
+end

data/lib/ncs_navigator/configuration/sampling_units.rb

@@ -0,0 +1,71 @@
+require 'ncs_navigator/configuration'
+
+class NcsNavigator::Configuration
+  class PrimarySamplingUnit < Struct.new(:id)
+    ##
+    # @return [Array<SamplingUnitArea>] the areas in this PSU.
+    def sampling_unit_areas
+      @sampling_unit_areas ||= []
+    end
+
+    ##
+    # @return [Array<SecondarySamplingUnit>] the SSUs in this PSU.
+    def secondary_sampling_units
+      sampling_unit_areas.collect(&:secondary_sampling_units).flatten
+    end
+
+    alias :areas :sampling_unit_areas
+    alias :ssus :secondary_sampling_units
+  end
+
+  ##
+  # NCS Navigator defines the concept of an "area" encompassing one or
+  # more SSUs. See {file:sample_configuration.ini} for more information.
+  class SamplingUnitArea < Struct.new(:name, :primary_sampling_unit)
+    def initialize(*)
+      super
+      primary_sampling_unit.sampling_unit_areas << self
+    end
+
+    ##
+    # @return [Array<SecondarySamplingUnit>] the SSUs in this area.
+    def secondary_sampling_units
+      @secondary_sampling_units ||= []
+    end
+
+    alias :psu :primary_sampling_unit
+    alias :ssus :secondary_sampling_units
+  end
+
+  class SecondarySamplingUnit < Struct.new(:id, :name, :sampling_unit_area)
+    def initialize(*)
+      super
+      sampling_unit_area.secondary_sampling_units << self
+    end
+
+    ##
+    # @return [PrimarySamplingUnit] the PSU to which this SSU belongs.
+    def primary_sampling_unit
+      area.psu
+    end
+
+    ##
+    # @return [TertiarySamplingUnit] any TSUs defined for this SSU.
+    def tertiary_sampling_units
+      @tertiary_sampling_units ||= []
+    end
+
+    alias :psu :primary_sampling_unit
+    alias :area :sampling_unit_area
+    alias :tsus :tertiary_sampling_units
+  end
+
+  class TertiarySamplingUnit < Struct.new(:id, :name, :secondary_sampling_unit)
+    def initialize(*)
+      super
+      secondary_sampling_unit.tertiary_sampling_units << self
+    end
+
+    alias :ssu :secondary_sampling_unit
+  end
+end

data/lib/ncs_navigator/configuration/version.rb

@@ -0,0 +1,5 @@
+module NcsNavigator
+  class Configuration
+    VERSION = "0.0.1"
+  end
+end

data/lib/ncs_navigator/configuration.rb

@@ -0,0 +1,381 @@
+require 'inifile'
+require 'pathname'
+require 'fastercsv'
+require 'uri'
+
+module NcsNavigator
+  # Additions to the root module are defined here instead of in
+  # lib/ncs_navigator.rb to avoid conflicts with other gems. There is
+  # no single gem which defines the NcsNavigator module, so no gem
+  # should respond when `require`ing 'ncs_navigator'.
+
+  ##
+  # The location from which the global configuration instance is read
+  # if a global instance is not explicitly set.
+  DEFAULT_CONFIGURATION_PATH = '/etc/nubic/ncs/navigator.ini'
+
+  ##
+  # The global configuration instance. Automatically instantiated on
+  # first reference from {.DEFAULT_CONFIGURATION_PATH} if it is not
+  # set explicitly.
+  #
+  # @return [Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new(DEFAULT_CONFIGURATION_PATH)
+  end
+
+  ##
+  # Replaces the global configuration with a provided instance.
+  # Set to `nil` to reload from {.DEFAULT_CONFIGURATION_PATH}.
+  #
+  # @param [Configuration,nil] config the new configuration
+  # @return [void]
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  ##
+  # The typed access point for the common configuration in the NCS
+  # Navigator suite.
+  class Configuration
+    autoload :VERSION, 'ncs_navigator/configuration/version'
+
+    autoload :PrimarySamplingUnit,   'ncs_navigator/configuration/sampling_units'
+    autoload :SecondarySamplingUnit, 'ncs_navigator/configuration/sampling_units'
+    autoload :TertiarySamplingUnit,  'ncs_navigator/configuration/sampling_units'
+    autoload :SamplingUnitArea,      'ncs_navigator/configuration/sampling_units'
+
+    ######
+
+    APPLICATION_SECTIONS = ['Staff Portal', 'Core', 'PSC']
+
+    class << self
+      ##
+      # Defines a mapping from the configuration file to an attribute
+      # on this class.
+      #
+      # @param [Symbol] name the name of the attribute.
+      # @param [String] section the section of the configuration file
+      #   from which it is read.
+      # @param [String] key the configuration key within the section
+      #   for the attribute.
+      # @param [Class] type the type to which the configuration value
+      #   should be coerced.
+      # @param [Hash] options additional options controlling the
+      #   behavior of the attribute.
+      # @option options [Boolean] :required (false) is the
+      #   configuration property mandatory? If it is, reading the
+      #   configuration will fail if it is not provided or is blank.
+      # @option options [Object] :default the default value for the
+      #   configuration property.
+      #
+      # @return [void]
+      def configuration_attribute(name, section, key, type, options={})
+        configuration_attributes << ConfigurationAttribute.new(name, section, key, type, options)
+        attr_accessor name
+      end
+
+      ##
+      # @private used by instances, but not intended to be public.
+      def configuration_attributes
+        @configuration_attributes ||= []
+      end
+
+      ##
+      # @private implementation detail
+      class ConfigurationAttribute < Struct.new(:name, :section, :key, :type, :options)
+        def extract_and_set(config, hash)
+          v = raw_value_from(hash)
+          v = coerce(v, config)
+          if v.nil? && options[:required]
+            fail "Please set a value for [#{section}]: #{key}"
+          end
+          config.send(:"#{name}=", v)
+        end
+
+        def raw_value_from(hash)
+          if hash[section]
+            hash[section][key]
+          end
+        end
+
+        def coerce(raw_value, config)
+          return options[:default] if raw_value.nil?
+          case
+          when type == String
+            raw_value.to_s
+          when type == Symbol
+            raw_value.to_sym
+          when type == Fixnum
+            raw_value.to_i
+          when type == Pathname
+            coerce_to_pathname(raw_value, config)
+          when type == URI
+            URI.parse(raw_value.to_s)
+          when type == 'Boolean'
+            raw_value.to_s.downcase.strip == 'true' ? true : false
+          else
+            fail "Do not know how to coerce to #{type} for #{name} from [#{section}]: #{key}"
+          end
+        end
+
+        def coerce_to_pathname(raw_value, config)
+          base = Pathname.new(raw_value.to_s)
+          if base.absolute? || !config.ini_filename
+            base
+          else
+            config.ini_filename.dirname + base
+          end
+        end
+      end
+    end
+
+    ##
+    # The file from which this configuration was initialized, if any.
+    #
+    # @return [Pathname]
+    attr_reader :ini_filename
+
+    # TODO: it would be nice if the macro below generated method doc
+    # for both the reader and the writer.
+
+    ##
+    # The SC_ID for the study center using this deployment of NCS
+    # Navigator. This value must match an ID in the MDES.
+    #
+    # @macro [attach] configuration_attribute
+    #   Read from the `[$2]` section, key `$3`.
+    #   @return [$4]
+    configuration_attribute :study_center_id, 'Study Center', 'sc_id', String,
+      :required => true
+
+    alias :sc_id :study_center_id
+
+    ##
+    # The name for the institutional identity used in this deployment
+    # of NCS Navigator. For instance, for the Greater Chicago Study
+    # Center, it is "Northwestern NetID". The default is "Username".
+    configuration_attribute :study_center_username, 'Study Center', 'username', String,
+      :default => 'Username'
+
+    ##
+    # The CSV describing the PSU, "sampling areas", SSUs, and (if
+    # applicable) TSUs for this center.
+    #
+    # The format is described in the comments in the
+    # {file:sample_configuration.ini sample INI}.
+    configuration_attribute :sampling_units_file, 'Study Center', 'sampling_units_file', Pathname,
+      :required => true
+
+    ##
+    # The image that should appear on the left side of the footer in
+    # Staff Portal and Core. This should be a path to a file on the
+    # deployed server.
+    configuration_attribute :footer_logo_left, 'Study Center', 'footer_logo_left', Pathname
+
+    ##
+    # The image that should appear on the right side of the footer in
+    # Staff Portal and Core. This should be a path to a file on the
+    # deployed server.
+    configuration_attribute :footer_logo_right, 'Study Center', 'footer_logo_right', Pathname
+
+    ##
+    # The text that should appear in the center of the footer in Staff
+    # Portal and Core. This is usually the center's contact
+    # information.
+    configuration_attribute :footer_text, 'Study Center', 'footer_text', String
+
+    ##
+    # The root URI for the Staff Portal deployment in this instance of
+    # the suite.
+    configuration_attribute :staff_portal_uri, 'Staff Portal', 'uri', URI, :required => true
+
+    ##
+    # The root URI for the NCS Navigator Core deployment in this instance of
+    # the suite.
+    configuration_attribute :core_uri, 'Core', 'uri', URI, :required => true
+
+    ##
+    # The root URI for the PSC deployment in this instance of
+    # the suite.
+    configuration_attribute :psc_uri, 'PSC', 'uri', URI, :required => true
+
+    ##
+    # The hostname of the SMTP server the suite should use to send
+    # mail.
+    configuration_attribute :smtp_host, 'SMTP', 'host', String, :default => 'localhost'
+
+    ##
+    # The port for the SMTP server the suite should use.
+    configuration_attribute :smtp_port, 'SMTP', 'port', Fixnum, :default => 25
+
+    ##
+    # The the HELO domain for the SMTP server, if any.
+    configuration_attribute :smtp_helo_domain, 'SMTP', 'domain', String
+
+    ##
+    # The type of authentication needed for the SMTP server, if any.
+    configuration_attribute :smtp_authentication_method, 'SMTP', 'authentication', Symbol
+
+    ##
+    # The username to use when authenticating to the SMTP server, if
+    # authentication is required.
+    configuration_attribute :smtp_username, 'SMTP', 'username', String
+
+    ##
+    # The password to use when authenticating to the SMTP server, if
+    # authentication is required.
+    configuration_attribute :smtp_password, 'SMTP', 'password', String
+
+    ##
+    # Whether to try to use STARTTLS if the SMTP server supports
+    # it. Defaults to false.
+    configuration_attribute :smtp_starttls, 'SMTP', 'starttls', 'Boolean', :default => false
+
+    ##
+    # Creates a new Configuration.
+    #
+    # @param [String, Hash] source the basis for this
+    #   configuration. If it's a `String`, it's interpreted as a the
+    #   filename for an INI file ({file:sample_configuration.ini
+    #   sample}). If it's a `Hash`, it should have two levels. The
+    #   first level represents the sections and the second level the
+    #   keys and values.
+    def initialize(source)
+      case source
+      when String
+        init_from_ini(source)
+      else
+        init_from_hash(source)
+      end
+    end
+
+    def init_from_ini(filename)
+      if File.readable?(filename)
+        @ini_filename = Pathname.new(filename)
+        init_from_hash(IniFile.new(filename).to_h)
+      else
+        raise Error.new("NCS Navigator configuration file #{filename.inspect} does not exist or is not readable.")
+      end
+    end
+    private :init_from_ini
+
+    def init_from_hash(h)
+      h = stringify_keys(h)
+      self.class.configuration_attributes.each do |attr|
+        attr.extract_and_set(self, h)
+      end
+      @application_sections = APPLICATION_SECTIONS.inject({}) do |s, section|
+        s[section] = h[section].dup if h[section]
+        s
+      end
+    end
+    private :init_from_hash
+
+    def stringify_keys(h)
+      h.dup.tap do |z|
+        z.keys.each do |k|
+          v = z.delete(k)
+          z[k.to_s] =
+            case v
+            when Hash
+              stringify_keys(v)
+            else
+              v
+            end
+        end
+      end
+    end
+    private :stringify_keys
+
+    ##
+    # @return [Array<SamplingUnitArea>] the areas defined in {#sampling_units_file}.
+    def sampling_unit_areas
+      @sampling_unit_areas ||= read_sampling_unit_areas
+    end
+    alias :areas :sampling_unit_areas
+
+    def read_sampling_unit_areas
+      psus = {}
+      areas = {}
+      ssus = {}
+
+      unless sampling_units_file.readable?
+        raise Error.new("Could not read sampling units CSV #{sampling_units_file}")
+      end
+
+      FasterCSV.foreach(sampling_units_file, :headers => true) do |row|
+        psu = (psus[row['PSU_ID']] ||= PrimarySamplingUnit.new(row['PSU_ID']))
+        area = (areas[row['AREA']] ||= SamplingUnitArea.new(row['AREA'], psu))
+        ssu = (ssus[row['SSU_ID']] ||= SecondarySamplingUnit.new(row['SSU_ID'], row['SSU_NAME'], area))
+        if row['TSU_ID']
+          TertiarySamplingUnit.new(row['TSU_ID'], row['TSU_NAME'], ssu)
+        end
+      end
+
+      areas.values
+    end
+    private :read_sampling_unit_areas
+
+    ##
+    # @return [Array<PrimarySamplingUnit>] the PSUs defined in {#sampling_units_file}.
+    def primary_sampling_units
+      @primary_sampling_units ||= sampling_unit_areas.collect(&:primary_sampling_unit).uniq
+    end
+    alias :psus :primary_sampling_units
+
+    ##
+    # @return [Array<SecondarySamplingUnit>] the SSUs defined in {#sampling_units_file}.
+    def secondary_sampling_units
+      @secondary_sampling_units ||= sampling_unit_areas.collect(&:secondary_sampling_units).flatten
+    end
+    alias :ssus :secondary_sampling_units
+
+    ##
+    # Converts {#footer_text} into equivalent HTML.
+    #
+    # @return [String]
+    def footer_center_html
+      return nil unless footer_text
+      html = footer_text.split("\n").join("<br>\n")
+      if html.respond_to?(:html_safe)
+        html.html_safe
+      else
+        html
+      end
+    end
+
+    APPLICATION_SECTIONS.each do |section|
+      ##
+      # Exposes all the values from the [#{section}] section. This
+      # allows for flexibility in adding new options, with the downside
+      # that they are not automatically coerced or documented.
+      #
+      # @return [Hash<String, String>]
+      define_method section.downcase.gsub(' ', '_').to_sym do
+        @application_sections[section] ||= {}
+      end
+    end
+
+    ##
+    # Provides a configuration hash suitable for passing to
+    # `ActionMailer::Base.smtp_settings`.
+    #
+    # @return [Hash<Symbol, Object>]
+    def action_mailer_smtp_settings
+      Hash[
+        {
+          :address => smtp_host,
+          :port => smtp_port,
+          :domain => smtp_helo_domain,
+          :user_name => smtp_username,
+          :password => smtp_password,
+          :authentication => smtp_authentication_method,
+          :enable_starttls_auto => smtp_starttls
+        }.select { |k, v| v }
+      ]
+    end
+
+    class Error < StandardError; end
+  end
+end

data/ncs_navigator_configuration.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "ncs_navigator/configuration/version"
+
+Gem::Specification.new do |s|
+  s.name        = "ncs_navigator_configuration"
+  s.version     = NcsNavigator::Configuration::VERSION
+  s.authors     = ["Rhett Sutphin"]
+  s.email       = ["r-sutphin@northwestern.edu"]
+  s.homepage    = ""
+  s.summary     = %q{Common configuration elements for the NCS Navigator suite}
+  s.description = %q{
+    An internal component of the NCS Navigator suite, this gem provides a common view
+    onto shared configuration elements.
+  }
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'ncs_mdes', '~> 0.4'
+  s.add_dependency 'inifile', '~> 0.4.1'
+  s.add_dependency 'fastercsv', '~> 1.5'
+
+  s.add_development_dependency 'rake', '~> 0.9.2'
+  s.add_development_dependency 'rspec', '~> 2.6'
+  s.add_development_dependency 'yard', '~> 0.7.2'
+  s.add_development_dependency 'fakefs', '~> 0.3'
+end

data/sample_configuration.ini

@@ -0,0 +1,111 @@
+# @markup ruby
+# @title sample_configuration.ini
+
+# Sample common configuration for NCS Navigator. By default the suite
+# applications will expect to find a customized version of this file
+# in /etc/nubic/ncs/navigator.ini.
+
+[Study Center]
+# Information about the study center which is using this deployment of
+# NCS Navigator. Each NCS Navigator instance is only for one study
+# center.
+
+# The ID for the study center from the MDES
+sc_id = "20000000"
+
+# A pointer to a CSV describing the sampling units for this study
+# center.  If the path is not absolute it will be resolved relative to
+# this file.
+#
+# The CSV must have the following header (along with the contents it
+# implies):
+#
+#   PSU_ID, AREA, SSU_ID, SSU_NAME, TSU_ID, TSU_NAME
+#
+# While this format allows for multiple PSUs, NCS Navigator currently
+# only supports one per deployment. This will change in the future
+# when multiple PSUs are active per center.
+#
+# TSU_ID and TSU_NAME may be omitted for centers that are not on
+# Hi-Lo.
+#
+# AREA is an intermediate concept introduced by NCS Navigator. It
+# allows the grouping of one or more SSUs for ease of reporting
+# something (e.g., outreach events) across all of them. If a center
+# doesn't wish to make use of this concept, the AREA should be made
+# the same as the SSU_NAME.
+sampling_units_file = "sample_ssus.csv"
+
+# The name of the institutional user identity used in NCS
+# Navigator. E.g., for the Greater Chicago Study Center, this is the
+# Northwestern NetID. The default is "Username" if nothing is
+# specifed.
+#username = "NetID"
+
+# The absolute path to local files containing logos that should appear
+# on either end of the footer in Staff Portal and Core.
+#footer_logo_left = "/etc/nubic/ncs/logos/sc_20000000L.png"
+#footer_logo_right = "/etc/nubic/ncs/logos/sc_20000000R.png"
+
+# The text that should appear in the center of the footer in Staff
+# Portal and Core. Line breaks in this text will be preserved.
+footer_text = "National Children’s Study - Greater Chicago Study Center
+Institute for Healthcare Studies, Feinberg School of Medicine
+Northwestern University
+420 East Superior, 10th Floor
+Chicago, IL 60611"
+
+[Staff Portal]
+# Configuration options which are used by or which describe Staff
+# Portal in this instance of the suite.
+
+# The root URI for Staff Portal.
+uri = "https://staffportal.greaterchicagoncs.org/"
+
+# The e-mail address from which mail sent by Staff Pportal will
+# appear to come.
+mail_from = "staffportal@greaterchicagoncs.org"
+
+[Core]
+# Configuration options which are used by or which describe NCS
+# Navigator Core in this instance of the suite.
+
+# The root URI for NCS Navigator Core.
+uri = "https://ncsnavigator.greaterchicagoncs.org/"
+
+[PSC]
+# Configuration options which describe PSC as used by this instance of
+# the suite. (For now, PSC's own configuration options must be set
+# through its configuration interfaces.)
+
+# The root URI for PSC.
+uri = "https://calendar.greaterchicagoncs.org/"
+
+[SMTP]
+# Configuration for the SMTP server for MDES Warehouse, Staff Portal,
+# and NCS Navigator Core.
+
+# The hostname or IP of the SMTP server to use to send mail from the
+# suite. Default is localhost.
+#host = "localhost"
+
+# The port to use to communicate with the SMTP server. Default is 25.
+#port = "25"
+
+# The domain to use in SMTP HELO, if necessary. Default is none.
+#domain =
+
+# The type of authentication your SMTP server uses. Default is
+# none. Legal values are "plain", "login", or "cram_md5".
+#authentication =
+
+# The username to use to authenticate to the SMTP server, if
+# necessary. Default is none.
+#username =
+
+# The password to use to authenticate to the SMTP server, if
+# necessary. Default is none.
+#password =
+
+# Whether to use STARTTLS if your SMTP server supports it. Default is false.
+#starttls = false