entitlements 0.1.7

data/lib/entitlements/data/groups/calculated.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require_relative "calculated/base"
+require_relative "calculated/ruby"
+require_relative "calculated/text"
+require_relative "calculated/yaml"
+
+# Calculate groups that should exist and the contents of each based on a set of rules
+# defined within a directory. The calculation of members is global across the entire
+# entitlements system, so this is a singleton class.
+
+module Entitlements
+  class Data
+    class Groups
+      class Calculated
+        include ::Contracts::Core
+        C = ::Contracts
+
+        FILE_EXTENSIONS = {
+          "rb"   => "Entitlements::Data::Groups::Calculated::Ruby",
+          "txt"  => "Entitlements::Data::Groups::Calculated::Text",
+          "yaml" => "Entitlements::Data::Groups::Calculated::YAML"
+        }
+
+        @groups_in_ou_cache = {}
+        @groups_cache = {}
+        @config_cache = {}
+
+        # Reset all module state
+        #
+        # Takes no arguments
+        def self.reset!
+          @rules_index = {
+            "group"    => Entitlements::Data::Groups::Calculated::Rules::Group,
+            "username" => Entitlements::Data::Groups::Calculated::Rules::Username
+          }
+
+          @filters_index = {}
+          @groups_in_ou_cache = {}
+          @groups_cache = {}
+          @config_cache = {}
+        end
+
+        # Construct a group object.
+        #
+        # Takes no arguments.
+        #
+        # Returns a Entitlements::Models::Group object.
+        Contract String => Entitlements::Models::Group
+        def self.read(dn)
+          return @groups_cache[dn] if @groups_cache[dn]
+          raise "read(#{dn.inspect}) does not support calculation at this time. Please use read_all() first to build cache."
+        end
+
+        # Calculate all groups within the specified OU and enumerate their members.
+        # Results are cached for future runs so the read() method is faster.
+        #
+        # ou_key  - String with the key from the configuration file.
+        # cfg_obj - Hash with the configuration for that key from the configuration file.
+        #
+        # Returns a Set of Strings (DNs) of the groups in this OU.
+        Contract String, C::HashOf[String => C::Any], C::KeywordArgs[
+          skip_broken_references: C::Optional[C::Bool]
+        ] => C::SetOf[String]
+        def self.read_all(ou_key, cfg_obj, skip_broken_references: false)
+          return read_mirror(ou_key, cfg_obj) if cfg_obj["mirror"]
+
+          @config_cache[ou_key] ||= cfg_obj
+          @groups_in_ou_cache[ou_key] ||= begin
+            Entitlements.logger.debug "Calculating all groups for #{ou_key}"
+            Entitlements.logger.debug "!!! skip_broken_references is enabled" if skip_broken_references
+
+            result = Set.new
+            Entitlements.cache[:file_objects] ||= {}
+
+            # Iterate over all the files in the configuration directory for this OU
+            path = Entitlements::Util::Util.path_for_group(ou_key)
+            Dir.glob(File.join(path, "*")).each do |filename|
+              # If it's a directory, skip it for now.
+              if File.directory?(filename)
+                next
+              end
+
+              # If the file is ignored (e.g. documentation) then skip it.
+              if Entitlements::IGNORED_FILES.member?(File.basename(filename))
+                next
+              end
+
+              # Determine the group DN. The CN will be the filname without its extension.
+              file_without_extension = File.basename(filename).sub(/\.\w+\z/, "")
+              unless file_without_extension =~ /\A[\w\-]+\z/
+                raise "Illegal LDAP group name #{file_without_extension.inspect} in #{ou_key}!"
+              end
+              group_dn = ["cn=#{file_without_extension}", cfg_obj.fetch("base")].join(",")
+
+              # Use the ruleset to build the group.
+              options = { skip_broken_references: skip_broken_references }
+
+              Entitlements.cache[:file_objects][filename] ||= ruleset(filename: filename, config: cfg_obj, options: options)
+              @groups_cache[group_dn] = Entitlements::Models::Group.new(
+                dn: group_dn,
+                members: Entitlements.cache[:file_objects][filename].modified_filtered_members,
+                description: Entitlements.cache[:file_objects][filename].description,
+                metadata: Entitlements.cache[:file_objects][filename].metadata.merge("_filename" => filename)
+              )
+              result.add group_dn
+            end
+
+            result
+          end
+        end
+
+        # Return the group cache as a hash.
+        #
+        # Takes no arguments.
+        #
+        # Returns a hash { dn => Entitlements::Models::Group }
+        # :nocov:
+        Contract C::None => C::HashOf[String => Entitlements::Models::Group]
+        def self.to_h
+          @groups_cache
+        end
+        # :nocov:
+
+        # Get the entire output organized by OU.
+        #
+        # Takes no arguments.
+        #
+        # Returns a Hash of OU to the configuration and group objects it contains.
+        Contract C::None => C::HashOf[String => { config: C::HashOf[String => C::Any], groups: C::HashOf[String => Entitlements::Models::Group]}]
+        def self.all_groups
+          @groups_in_ou_cache.map do |ou_key, dn_in_ou|
+            if @config_cache.key?(ou_key)
+              [
+                ou_key,
+                {
+                  config: @config_cache[ou_key],
+                  groups: dn_in_ou.sort.map { |dn| [dn, @groups_cache.fetch(dn)] }.to_h
+                }
+              ]
+            else
+              nil
+            end
+          end.compact.to_h
+        end
+
+        # Calculate the groups within the specified mirrored OU. This requires that
+        # read_all() has run already on the mirrored OU. This will not re-calculate
+        # the results, but rather just duplicate the results and adjust the OUs.
+        #
+        # ou_key  - String with the key from the configuration file.
+        # cfg_obj - Hash with the configuration for that key from the configuration file.
+        #
+        # Returns a Set of Strings (DNs) of the groups in this OU.
+        Contract String, C::HashOf[String => C::Any] => C::SetOf[String]
+        def self.read_mirror(ou_key, cfg_obj)
+          @groups_in_ou_cache[ou_key] ||= begin
+            Entitlements.logger.debug "Mirroring #{ou_key} from #{cfg_obj['mirror']}"
+
+            unless @groups_in_ou_cache[cfg_obj["mirror"]]
+              raise "Cannot read_mirror on #{ou_key.inspect} because read_all has not occurred on #{cfg_obj['mirror'].inspect}!"
+            end
+
+            result = Set.new
+            @groups_in_ou_cache[cfg_obj["mirror"]].each do |source_dn|
+              source_group = @groups_cache[source_dn]
+              unless source_group
+                raise "No group has been calculated for #{source_dn.inspect}!"
+              end
+
+              new_dn = ["cn=#{source_group.cn}", cfg_obj["base"]].join(",")
+              @groups_cache[new_dn] ||= source_group.copy_of(new_dn)
+              result.add new_dn
+            end
+
+            result
+          end
+        end
+
+        # Construct the ruleset object for a given filename.
+        #
+        # filename - A String with the filename.
+        #
+        # Returns an Entitlements::Data::Groups::Calculated::* object.
+        Contract C::KeywordArgs[
+          filename: String,
+          config: C::HashOf[String => C::Any],
+          options: C::Optional[C::HashOf[Symbol => C::Any]]
+        ] => C::Or[
+          Entitlements::Data::Groups::Calculated::Ruby,
+          Entitlements::Data::Groups::Calculated::Text,
+          Entitlements::Data::Groups::Calculated::YAML,
+        ]
+        def self.ruleset(filename:, config:, options: {})
+          unless filename =~ /\.(\w+)\z/
+            raise ArgumentError, "Unable to determine the extension on #{filename.inspect}!"
+          end
+          ext = Regexp.last_match(1)
+
+          unless FILE_EXTENSIONS[ext]
+            Entitlements.logger.fatal "Unable to map filename #{filename.inspect} to a ruleset object!"
+            raise ArgumentError, "Unable to map filename #{filename.inspect} to a ruleset object!"
+          end
+
+          if config.key?("allowed_types")
+            unless config["allowed_types"].is_a?(Array)
+              Entitlements.logger.fatal "Configuration error: allowed_types should be an Array, got #{config['allowed_types'].inspect}"
+              raise ArgumentError, "Configuration error: allowed_types should be an Array, got #{config['allowed_types'].class}!"
+            end
+
+            unless config["allowed_types"].include?(ext)
+              allowed_join = config["allowed_types"].join(",")
+              Entitlements.logger.fatal "Files with extension #{ext.inspect} are not allowed in this OU! Allowed: #{allowed_join}!"
+              raise ArgumentError, "Files with extension #{ext.inspect} are not allowed in this OU! Allowed: #{allowed_join}!"
+            end
+          end
+
+          clazz = Kernel.const_get(FILE_EXTENSIONS[ext])
+          clazz.new(filename: filename, config: config, options: options)
+        end
+
+        #########################
+        # This section is handled as a class variable not an instance variable because rule definitions
+        # are global throughout the program.
+        #########################
+
+        @rules_index = {
+          "group"    => Entitlements::Data::Groups::Calculated::Rules::Group,
+          "username" => Entitlements::Data::Groups::Calculated::Rules::Username
+        }
+
+        @filters_index = {}
+
+        # Retrieve the current rules index from the class.
+        #
+        # Takes no arguments.
+        #
+        # Returns a Hash.
+        Contract C::None => C::HashOf[String => Class]
+        def self.rules_index
+          @rules_index
+        end
+
+        # Retrieve the current filters index from the class.
+        #
+        # Takes no arguments.
+        #
+        # Returns a Hash.
+        Contract C::None => C::HashOf[String => Object]
+        def self.filters_index
+          @filters_index
+        end
+
+        # Retrieve the filters in the format used as default / starting point in other parts
+        # of the program: { "filter_name_1" => :none, "filter_name_2" => :none }
+        #
+        # Takes no arguments.
+        #
+        # Returns a Hash in the indicated format.
+        def self.filters_default
+          @filters_index.map { |k, _| [k, :none] }.to_h
+        end
+
+        # Register a rule (requires namespace and class references). Methods are registered
+        # per rule, not per instantiation.
+        #
+        # rule_name - String with the rule name.
+        # clazz     - Class that implements the rule.
+        #
+        # Returns the class that implements the rule.
+        Contract String, Class => Class
+        def self.register_rule(rule_name, clazz)
+          @rules_index[rule_name] = clazz
+        end
+
+        # Register a filter (requires namespace and object references). Named filters are instantiated
+        # objects. It's possible to have multiple instantiations of the same class of filter.
+        #
+        # filter_name - String with the filter name.
+        # filter_cfg  - Hash with a configuration for the filter.
+        #
+        # Returns the configuration of the filter object (a hash).
+        Contract String, C::HashOf[Symbol => Object] => C::HashOf[Symbol => Object]
+        def self.register_filter(filter_name, filter_cfg)
+          @filters_index[filter_name] = filter_cfg
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/data/groups.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "groups/cached"
+require_relative "groups/calculated"
+
+module Entitlements
+  class Data
+    class Groups
+      class DuplicateGroupError < RuntimeError; end
+      class GroupNotFoundError < RuntimeError; end
+    end
+  end
+end

data/lib/entitlements/data/people/combined.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Entitlements
+  class Data
+    class People
+      class Combined
+        include ::Contracts::Core
+        C = ::Contracts
+
+        PARAMETERS = {
+          "operator"   => { required: true, type: String },
+          "components" => { required: true, type: Array },
+        }
+
+        # Fingerprint for the object based on unique parameters from the group configuration. If the fingerprint
+        # matches the same object should be re-used. This will raise an error if insufficient configuration is
+        # given.
+        #
+        # config - Hash of configuration values as may be found in the Entitlements configuration file.
+        #
+        # Returns a String with the "fingerprint" for this configuration.
+        Contract C::HashOf[String => C::Any] => String
+        def self.fingerprint(config)
+          # Fingerprint of the combined provider is the fingerprint of each constitutent provider. Then serialize
+          # to JSON to account for the and/or operator that is part of this configuration. Note: this method might
+          # end up being called recursively depending on the complexity of the combined configuration.
+          fingerprints = config["components"].map do |component|
+            Entitlements::Data::People.class_for_config(component).fingerprint(component.fetch("config"))
+          end
+
+          JSON.generate(config.fetch("operator") => fingerprints)
+        end
+
+        # Construct this object based on parameters in a group configuration. This is the direct translation
+        # between the Entitlements configuration file (which is always a Hash with configuration values) and
+        # the object constructed from this class (which can have whatever structure makes sense).
+        #
+        # config - Hash of configuration values as may be found in the Entitlements configuration file.
+        #
+        # Returns Entitlements::Data::People::Combined object.
+        # :nocov:
+        Contract C::HashOf[String => C::Any] => Entitlements::Data::People::Combined
+        def self.new_from_config(config)
+          new(
+            operator: config.fetch("operator"),
+            components: config.fetch("components")
+          )
+        end
+        # :nocov:
+
+        # Validate configuration options.
+        #
+        # key    - String with the name of the data source.
+        # config - Hash with the configuration data.
+        #
+        # Returns nothing.
+        Contract String, C::HashOf[String => C::Any] => nil
+        def self.validate_config!(key, config)
+          text = "Combined people configuration for data source #{key.inspect}"
+          Entitlements::Util::Util.validate_attr!(PARAMETERS, config, text)
+
+          unless %w[and or].include?(config["operator"])
+            raise ArgumentError, "In #{key}, expected 'operator' to be either 'and' or 'or', not #{config['operator'].inspect}!"
+          end
+
+          component_spec = {
+            "config" => { required: true, type: Hash },
+            "name"   => { required: false, type: String },
+            "type"   => { required: true, type: String },
+          }
+
+          if config["components"].empty?
+            raise ArgumentError, "In #{key}, the array of components cannot be empty!"
+          end
+
+          config["components"].each do |component|
+            if component.is_a?(Hash)
+              component_name = component.fetch("name", component.inspect)
+              component_text = "Combined people configuration #{key.inspect} component #{component_name}"
+              Entitlements::Util::Util.validate_attr!(component_spec, component, component_text)
+              clazz = Entitlements::Data::People.class_for_config(component)
+              clazz.validate_config!("#{key}:#{component_name}", component.fetch("config"))
+            elsif component.is_a?(String)
+              if Entitlements.config.fetch("people", {}).fetch(component, nil)
+                resolved_component = Entitlements.config["people"][component]
+                clazz = Entitlements::Data::People.class_for_config(resolved_component)
+                clazz.validate_config!(component, resolved_component.fetch("config"))
+              else
+                raise ArgumentError, "In #{key}, reference to invalid component #{component.inspect}!"
+              end
+            else
+              raise ArgumentError, "In #{key}, expected array of hashes/strings but got #{component.inspect}!"
+            end
+          end
+
+          nil
+        end
+
+        # Constructor.
+        #
+        Contract C::KeywordArgs[
+          operator: String,
+          components: C::ArrayOf[C::HashOf[String => C::Any]]
+        ] => C::Any
+        def initialize(operator:, components:)
+          @combined = { operator: operator }
+          @combined[:components] = components.map do |component|
+            clazz = Entitlements::Data::People.class_for_config(component)
+            clazz.new_from_config(component["config"])
+          end
+          @people = nil
+        end
+
+        # Read in the people from a combined provider. Cache result for later access.
+        #
+        # uid - Optionally a uid to return. If not specified, returns the entire hash.
+        #
+        # Returns Hash of { uid => Entitlements::Models::Person } or one Entitlements::Models::Person.
+        Contract C::Maybe[String] => C::Or[Entitlements::Models::Person, C::HashOf[String => Entitlements::Models::Person]]
+        def read(uid = nil)
+          @people ||= read_entire_hash
+          return @people unless uid
+
+          @people_downcase ||= @people.map { |people_uid, _data| [people_uid.downcase, people_uid] }.to_h
+          unless @people_downcase.key?(uid.downcase)
+            raise Entitlements::Data::People::NoSuchPersonError, "read(#{uid.inspect}) matched no known person"
+          end
+
+          @people[@people_downcase[uid.downcase]]
+        end
+
+        private
+
+        # Read an entire hash from the combined data source.
+        #
+        # Takes no arguments.
+        #
+        # Returns Hash of { uid => Entitlements::Models::Person }.
+        Contract C::None => C::HashOf[String => Entitlements::Models::Person]
+        def read_entire_hash
+          # @combined[:operator] is "or" or "and". Call the "read" method on each component and then assemble the
+          # results according to the specified logic. When a user is seen more than once, deconflict by using the *first*
+          # constructed person model that we have seen.
+          data = @combined[:components].map { |component| component.read }
+
+          result = {}
+          data.each do |data_hash|
+            data_hash.each do |user, user_data|
+              result[user] ||= user_data
+            end
+          end
+
+          if @combined[:operator] == "and"
+            users = Set.new(common_keys(data))
+            result.select! { |k, _| users.member?(k) }
+          end
+
+          result
+        end
+
+        # Given an arbitrary number of hashes, return the keys that are common in all of them.
+        # (hash1_keys & hash2_keys & hash3_keys)
+        #
+        # hashes - An array of hashes in which to find common keys.
+        #
+        # Returns an array of common elements.
+        Contract C::ArrayOf[Hash] => C::SetOf[C::Any]
+        def common_keys(hashes)
+          return Set.new if hashes.empty?
+
+          hash1 = hashes.shift
+          result = Set.new(hash1.keys)
+          hashes.each { |h| result = result & h.keys }
+          result
+        end
+
+        # Given an arbitrary number of hashes, return all keys seen in any of them.
+        # (hash1_keys | hash2_keys | hash3_keys)
+        #
+        # arrays - An array of arrays with elements in which to find any elements.
+        #
+        # Returns an array of all elements.
+        Contract C::ArrayOf[Hash] => C::SetOf[C::Any]
+        def all_keys(hashes)
+          return Set.new if hashes.empty?
+
+          hash1 = hashes.shift
+          result = Set.new(hash1.keys)
+          hashes.each { |h| result.merge(h.keys) }
+          result
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/data/people/dummy.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Data
+    class People
+      class Dummy
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # :nocov:
+
+        # Fingerprint for the object based on unique parameters from the group configuration. If the fingerprint
+        # matches the same object should be re-used. This will raise an error if insufficient configuration is
+        # given.
+        #
+        # config - Hash of configuration values as may be found in the Entitlements configuration file.
+        #
+        # Returns a String with the "fingerprint" for this configuration.
+        Contract C::HashOf[String => C::Any] => String
+        def self.fingerprint(_config)
+          "dummy"
+        end
+
+        # Construct this object based on parameters in a group configuration. This is the direct translation
+        # between the Entitlements configuration file (which is always a Hash with configuration values) and
+        # the object constructed from this class (which can have whatever structure makes sense).
+        #
+        # config - Hash of configuration values as may be found in the Entitlements configuration file.
+        #
+        # Returns Entitlements::Data::People::LDAP object.
+        Contract C::HashOf[String => C::Any] => Entitlements::Data::People::Dummy
+        def self.new_from_config(_config)
+          new
+        end
+
+        # Validate configuration options.
+        #
+        # key    - String with the name of the data source.
+        # config - Hash with the configuration data.
+        #
+        # Returns nothing.
+        Contract String, C::HashOf[String => C::Any] => nil
+        def self.validate_config!(_key, _config)
+          # This is always valid.
+        end
+
+        # Constructor.
+        #
+        # Takes no arguments.
+        Contract C::None => C::Any
+        def initialize
+          # This is pretty boring.
+        end
+
+        # This would normally read in all people and then return the hash or a specific person.
+        # In this case the hash is empty and there are no people.
+        #
+        # dn - Optionally a DN to return. If not specified, returns the entire hash.
+        #
+        # Returns empty hash or raises an error.
+        Contract C::Maybe[String] => C::Or[C::HashOf[String => Entitlements::Models::Person], Entitlements::Models::Person]
+        def read(dn = nil)
+          return {} if dn.nil?
+          raise Entitlements::Data::People::NoSuchPersonError, "read(#{dn.inspect}) matched no known person"
+        end
+
+        # :nocov:
+      end
+    end
+  end
+end