entitlements 0.1.7

data/lib/entitlements/data/people/ldap.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "net/ldap"
+
+module Entitlements
+  class Data
+    class People
+      class LDAP
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Default attributes
+        PEOPLE_ATTRIBUTES = %w[cn]
+        UID_ATTRIBUTE = "uid"
+
+        # Parameters
+        PARAMETERS = {
+          "base"                     => { required: true, type: String },
+          "ldap_binddn"              => { required: true, type: String },
+          "ldap_bindpw"              => { required: true, type: String },
+          "ldap_uri"                 => { required: true, type: String },
+          "ldap_ca_file"             => { required: false, type: String },
+          "person_dn_format"         => { required: true, type: String },
+          "disable_ssl_verification" => { required: false, type: [FalseClass, TrueClass] },
+          "additional_attributes"    => { required: false, type: Array },
+          "uid_attribute"            => { required: false, type: String }
+        }
+
+        # 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)
+          PARAMETERS.keys.map { |key| config[key].inspect }.join("||")
+        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.
+        # :nocov:
+        Contract C::HashOf[String => C::Any] => Entitlements::Data::People::LDAP
+        def self.new_from_config(config)
+          new(
+            ldap: Entitlements::Service::LDAP.new_with_cache(
+              addr: config.fetch("ldap_uri"),
+              binddn: config.fetch("ldap_binddn"),
+              bindpw: config.fetch("ldap_bindpw"),
+              ca_file: config.fetch("ldap_ca_file", ENV["LDAP_CACERT"]),
+              disable_ssl_verification: config.fetch("ldap_disable_ssl_verification", false),
+              person_dn_format: config.fetch("person_dn_format")
+            ),
+            people_ou: config.fetch("base"),
+            uid_attr: config.fetch("uid_attribute", UID_ATTRIBUTE),
+            people_attr: config.fetch("additional_attributes", PEOPLE_ATTRIBUTES)
+          )
+        end
+        # :nocov:
+
+        # Validate configuration options.
+        #
+        # key    - String with the name of the data source.
+        # config - Hash with the configuration data.
+        #
+        # Returns nothing.
+        # :nocov:
+        Contract String, C::HashOf[String => C::Any] => nil
+        def self.validate_config!(key, config)
+          text = "LDAP people configuration for data source #{key.inspect}"
+          Entitlements::Util::Util.validate_attr!(PARAMETERS, config, text)
+        end
+        # :nocov:
+
+        # Constructor.
+        #
+        # ldap        - Entitlements::Service::LDAP object
+        # people_ou   - String containing the OU in which people reside
+        # dn_format   - How to translate a UID to a DN (e.g. uid=%KEY%,ou=People,dc=kittens,dc=net)
+        # uid_attr    - Optional String with attribute name for the user ID (default: uid)
+        # people_attr - Optional Array of Strings attributes of people that should be fetched from LDAP
+        Contract C::KeywordArgs[
+          ldap: Entitlements::Service::LDAP,
+          people_ou: String,
+          uid_attr: C::Maybe[String],
+          people_attr: C::Maybe[C::ArrayOf[String]]
+        ] => C::Any
+        def initialize(ldap:, people_ou:, uid_attr: UID_ATTRIBUTE, people_attr: PEOPLE_ATTRIBUTES)
+          @ldap = ldap
+          @people_ou = people_ou
+          @uid_attr = uid_attr
+          @people_attr = people_attr
+        end
+
+        # Read in the people from LDAP. 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[C::HashOf[String => Entitlements::Models::Person], Entitlements::Models::Person]
+        def read(uid = nil)
+          @people ||= begin
+            Entitlements.logger.debug "Loading people from LDAP"
+            ldap.search(base: people_ou, filter: Net::LDAP::Filter.eq(uid_attr, "*"), attrs: people_attr.sort)
+              .map { |person_dn, entry| [Entitlements::Util::Util.first_attr(person_dn).downcase, entry_to_person(entry)] }
+              .to_h
+          end
+
+          return @people if uid.nil?
+          return @people[uid.downcase] if @people[uid.downcase]
+          raise Entitlements::Data::People::NoSuchPersonError, "read(#{uid.inspect}) matched no known person"
+        end
+
+        private
+
+        attr_reader :ldap, :people_ou, :uid_attr, :people_attr
+
+        # Construct an Entitlements::Models::Person from a Net::LDAP::Entry
+        #
+        # entry - The Net::LDAP::Entry
+        #
+        # Returns an Entitlements::Models::Person object.
+        Contract Net::LDAP::Entry => Entitlements::Models::Person
+        def entry_to_person(entry)
+          attributes = people_attr
+            .map { |k| [k.to_s, entry[k.to_sym]] }
+            .to_h
+          Entitlements::Models::Person.new(
+            uid: Entitlements::Util::Util.first_attr(entry.dn),
+            attributes: attributes
+          )
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/data/people/yaml.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Entitlements
+  class Data
+    class People
+      class YAML
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Parameters
+        PARAMETERS = {
+          "filename" => { required: true, type: String }
+        }
+
+        # 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)
+          PARAMETERS.keys.map { |key| config[key].inspect }.join("||")
+        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::YAML object.
+        # :nocov:
+        Contract C::HashOf[String => C::Any] => Entitlements::Data::People::YAML
+        def self.new_from_config(config)
+          new(filename: config.fetch("filename"))
+        end
+        # :nocov:
+
+        # Validate configuration options.
+        #
+        # key    - String with the name of the data source.
+        # config - Hash with the configuration data.
+        #
+        # Returns nothing.
+        # :nocov:
+        Contract String, C::HashOf[String => C::Any] => nil
+        def self.validate_config!(key, config)
+          text = "YAML people configuration for data source #{key.inspect}"
+          Entitlements::Util::Util.validate_attr!(PARAMETERS, config, text)
+        end
+        # :nocov:
+
+        # Constructor.
+        #
+        # filename  - String with the filename to read.
+        # people    - Optionally, Hash of { uid => Entitlements::Models::Person }
+        Contract C::KeywordArgs[
+          filename: String,
+          people: C::Maybe[C::HashOf[String => Entitlements::Models::Person]]
+        ] => C::Any
+        def initialize(filename:, people: nil)
+          @filename = filename
+          @people = people
+          @people_downcase = nil
+        end
+
+        # Read in the people from a file. 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 ||= begin
+            Entitlements.logger.debug "Loading people from #{filename.inspect}"
+            raw_person_data = ::YAML.load(File.read(filename)).to_h
+            raw_person_data.map do |id, data|
+              [id, Entitlements::Models::Person.new(uid: id, attributes: data)]
+            end.to_h
+          end
+          return @people if uid.nil?
+
+          # Requested a specific user ID
+          @people_downcase ||= @people.map { |person_uid, data| [person_uid.downcase, person_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
+
+        attr_reader :filename
+      end
+    end
+  end
+end

data/lib/entitlements/data/people.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "people/combined"
+require_relative "people/dummy"
+require_relative "people/ldap"
+require_relative "people/yaml"
+
+module Entitlements
+  class Data
+    class People
+      class NoSuchPersonError < RuntimeError; end
+
+      include ::Contracts::Core
+      C = ::Contracts
+
+      PEOPLE_CLASSES = {
+        "combined" => Entitlements::Data::People::Combined,
+        "dummy"    => Entitlements::Data::People::Dummy,
+        "ldap"     => Entitlements::Data::People::LDAP,
+        "yaml"     => Entitlements::Data::People::YAML
+      }
+
+      # Gets the class for the specified configuration. Basically this is a wrapper around PEOPLE_CLASSES
+      # with friendly error messages if a configuration is insufficient to select the class.
+      #
+      # config - Hash of configuration values as may be found in the Entitlements configuration file.
+      #
+      # Returns Entitlements::Data::People class.
+      Contract C::HashOf[String => C::Any] => Class
+      def self.class_for_config(config)
+        unless config.key?("type")
+          raise ArgumentError, "'type' is undefined in: #{config.inspect}"
+        end
+
+        unless Entitlements::Data::People::PEOPLE_CLASSES.key?(config["type"])
+          raise ArgumentError, "'type' #{config['type'].inspect} is invalid!"
+        end
+
+        Entitlements::Data::People::PEOPLE_CLASSES.fetch(config["type"])
+      end
+
+      # Constructor to build an object from the configuration file. Given a key in the `groups`
+      # section, check the `people` key for one or more data sources for people records. Construct
+      # the underlying object(s) as necessary while caching duplicate objects.
+      #
+      # config - Hash of configuration values as may be found in the Entitlements configuration file.
+      #
+      # Returns Entitlements::Data::People object backed by appropriate object(s).
+      Contract C::HashOf[String => C::Any] => C::Any
+      def self.new_from_config(config)
+        Entitlements.cache[:people_class] ||= {}
+        clazz = class_for_config(config)
+        fingerprint = clazz.fingerprint(config.fetch("config"))
+        Entitlements.cache[:people_class][fingerprint] ||= clazz.new_from_config(config.fetch("config"))
+      end
+    end
+  end
+end

data/lib/entitlements/extras/base.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Inherited methods for extras in this directory (or in other directories).
+
+module Entitlements
+  module Extras
+    class Base
+      include ::Contracts::Core
+      C = ::Contracts
+
+      # Retrieve the configuration for this extra from the Entitlements configuration
+      # file. Returns the hash of configuration if found, or an empty hash in all other
+      # cases.
+      #
+      # Takes no arguments.
+      #
+      # Returns a Hash.
+      Contract C::None => C::HashOf[String => C::Any]
+      def self.config
+        @extra_config ||= begin
+          # classname is something like "Entitlements::Extras::MyExtraClassName::Base" - want to pull
+          # out the "MyExtraClassName" from this string.
+          classname = self.to_s.split("::")[-2]
+          decamelized_class = Entitlements::Util::Util.decamelize(classname)
+          cfg = Entitlements.config.fetch("extras", {}).fetch(decamelized_class, nil)
+          cfg.is_a?(Hash) ? cfg : {}
+        end
+      end
+
+      # This is intended for unit tests to reset class variables.
+      #
+      # Takes no arguments.
+      #
+      # Returns nothing.
+      def self.reset!
+        @extra_config = nil
+      end
+    end
+  end
+end

data/lib/entitlements/extras/ldap_group/base.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Entitlements
+  module Extras
+    class LDAPGroup
+      class Base < Entitlements::Extras::Base
+        def self.init
+          require_relative "filters/member_of_ldap_group"
+          require_relative "rules/ldap_group"
+        end
+
+        def self.rules
+          %w[ldap_group]
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/extras/ldap_group/filters/member_of_ldap_group.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Filter class to remove members of a particular LDAP group.
+
+module Entitlements
+  module Extras
+    class LDAPGroup
+      class Filters
+        class MemberOfLDAPGroup < Entitlements::Data::Groups::Calculated::Filters::Base
+          include ::Contracts::Core
+          C = ::Contracts
+
+          # Determine if the member is filtered as per this definition. Return true if the member
+          # is to be filtered out, false if the member does not match the filter.
+          #
+          # member - Entitlements::Models::Person object
+          #
+          # Returns true if the person is to be filtered out, false otherwise.
+          Contract Entitlements::Models::Person => C::Bool
+          def filtered?(member)
+            return false if filter == :all
+            return false unless member_of_ldap_group?(member, config.fetch("ldap_group"))
+            return true if filter == :none
+            !member_of_filter?(member)
+          end
+
+          # Helper method: Determine if the person is a member of an LDAP group that exists in
+          # the directory but is not managed by entitlements.
+          #
+          # member   - Entitlements::Models::Person object
+          # group_dn - LDAP distinguished name of the group
+          #
+          # Returns true if a member of the group, false otherwise.
+          Contract Entitlements::Models::Person, String => C::Bool
+          def member_of_ldap_group?(member, group_dn)
+            Entitlements.cache[:member_of_ldap_group] ||= {}
+            Entitlements.cache[:member_of_ldap_group][group_dn] ||= begin
+              member_set = Entitlements::Extras::LDAPGroup::Rules::LDAPGroup.matches(value: group_dn)
+              member_set.map { |person| person.uid.downcase }
+            rescue Entitlements::Data::Groups::GroupNotFoundError
+              []
+            end
+
+            Entitlements.cache[:member_of_ldap_group][group_dn].include?(member.uid.downcase)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/extras/ldap_group/rules/ldap_group.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+# Is someone in an LDAP group?
+
+module Entitlements
+  module Extras
+    class LDAPGroup
+      class Rules
+        class LDAPGroup < Entitlements::Data::Groups::Calculated::Rules::Base
+          include ::Contracts::Core
+          C = ::Contracts
+
+          # Interface method: Get a Set[Entitlements::Models::Person] matching this condition.
+          #
+          # value    - The value to match.
+          # filename - Name of the file resulting in this rule being called
+          # options  - Optional hash of additional method-specific options
+          #
+          # Returns a Set[Entitlements::Models::Person].
+          Contract C::KeywordArgs[
+            value: String,
+            filename: C::Maybe[String],
+            options: C::Optional[C::HashOf[Symbol => C::Any]]
+          ] => C::SetOf[Entitlements::Models::Person]
+          def self.matches(value:, filename: nil, options: {})
+            Entitlements.cache[:ldap_cache] ||= {}
+            Entitlements.cache[:ldap_cache][value] ||= begin
+              entry = ldap.read(value)
+              unless entry
+                message = if filename
+                  "Failed to read ldap_group = #{value} (referenced in #{filename})"
+                else
+                  # :nocov:
+                  "Failed to read ldap_group = #{value}"
+                  # :nocov:
+                end
+                raise Entitlements::Data::Groups::GroupNotFoundError, message
+              end
+              Entitlements::Service::LDAP.entry_to_group(entry)
+            end
+            Entitlements.cache[:ldap_cache][value].members(people_obj: Entitlements.cache[:people_obj])
+          end
+
+          # Object to communicate with an LDAP backend.
+          #
+          # Takes no arguments.
+          #
+          # Returns a Entitlements::Service::LDAP object.
+          # :nocov:
+          Contract C::None => Entitlements::Service::LDAP
+          def self.ldap
+            @ldap ||= begin
+              config = Entitlements::Extras::LDAPGroup::Base.config
+              opts = {
+                addr: config.fetch("ldap_uri"),
+                binddn: config.fetch("ldap_binddn"),
+                bindpw: config.fetch("ldap_bindpw"),
+                ca_file: config.fetch("ldap_ca_file", ENV["LDAP_CACERT"]),
+                person_dn_format: config.fetch("person_dn_format")
+              }
+              opts[:disable_ssl_verification] = true if config.fetch("disable_ssl_verification", false)
+              Entitlements::Service::LDAP.new_with_cache(opts)
+            end
+          end
+          # :nocov:
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/extras/orgchart/base.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require "yaml"
+
+module Entitlements
+  module Extras
+    class Orgchart
+      class Base < Entitlements::Extras::Base
+        def self.init
+          require_relative "logic"
+          require_relative "person_methods"
+          require_relative "rules/direct_report"
+          require_relative "rules/management"
+        end
+
+        def self.rules
+          %w[direct_report management]
+        end
+
+        def self.person_methods
+          %w[manager]
+        end
+
+        def self.reset!
+          super
+          Entitlements::Extras::Orgchart::PersonMethods.reset!
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/extras/orgchart/logic.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+# Helper functions to implement our own business logic.
+
+module Entitlements
+  module Extras
+    class Orgchart
+      class Logic
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Constructor for the people logic engine. Pass in the indexed hash of people in the organization
+        # and this will handle indexing, caching, and reporting relationship logic.
+        #
+        # people_hash - A Hash of { dn => Entitlements::Models::Person LDAP Object }
+        Contract C::KeywordArgs[
+          people: C::HashOf[String => Entitlements::Models::Person],
+        ] => C::Any
+        def initialize(people:)
+          @people_hash = people.map { |uid, person| [uid.downcase, person] }.to_h
+          @direct_reports_cache = nil
+          @all_reports_cache = nil
+        end
+
+        # Calculate the direct reports of a given person, returning a Set of all of the people who report to
+        # that person. Does NOT return the manager themselves as part of the result set. Returns an empty set
+        # if the person has nobody directly reporting to them.
+        #
+        # manager - Entitlements::Models::Person who is the manager or higher
+        #
+        # Returns a Set of Entitlements::Models::Person's.
+        Contract Entitlements::Models::Person => C::SetOf[Entitlements::Models::Person]
+        def direct_reports(manager)
+          manager_uid = manager.uid.downcase
+          direct_reports_cache.key?(manager_uid) ? direct_reports_cache[manager_uid] : Set.new
+        end
+
+        # Calculate the all reports of a given person, returning a Set of all of the people who report to
+        # that person directly or indirectly. Does NOT return the manager themselves as part of the result
+        # set. Returns an empty set if the person has nobody reporting to them.
+        #
+        # manager - Entitlements::Models::Person who is the manager or higher
+        #
+        # Returns a Set of LDAP object Entitlements::Models::Persons.
+        Contract Entitlements::Models::Person => C::SetOf[Entitlements::Models::Person]
+        def all_reports(manager)
+          manager_uid = manager.uid.downcase
+          all_reports_cache.key?(manager_uid) ? all_reports_cache[manager_uid] : Set.new
+        end
+
+        # Calculate the management chain for the person, returning a Set of all managers in that chain all
+        # the way to the top of the tree.
+        #
+        # person - Entitlements::Models::Person object
+        #
+        # Returns a Set of LDAP object openstructs.
+        Contract Entitlements::Models::Person => C::SetOf[Entitlements::Models::Person]
+        def management_chain(person)
+          person_uid = person.uid.downcase
+
+          @management_chain_cache ||= {}
+          return @management_chain_cache[person_uid] if @management_chain_cache[person_uid].is_a?(Set)
+
+          @management_chain_cache[person_uid] = Set.new
+          if person.manager && person.manager != person.uid
+            person_manager_uid = person.manager.downcase
+            unless @people_hash.key?(person_manager_uid)
+              # :nocov:
+              raise ArgumentError, "Manager #{person.manager.inspect} for person #{person.uid.inspect} does not exist!"
+              # :nocov:
+            end
+            # The recursive logic here will also define the management_chain_cache value for the manager,
+            # and when calculating that it will define the management_chain_cache value for that manager's manager,
+            # and so on. This ensures that each person's manager is only computed one time (when it's used) and
+            # subsequent lookups are all faster.
+            @management_chain_cache[person_uid].add @people_hash[person_manager_uid]
+            @management_chain_cache[person_uid].merge management_chain(@people_hash[person_manager_uid])
+          end
+          @management_chain_cache[person_uid]
+        end
+
+        private
+
+        # Iterate through the entire employee list and build up the lists of direct reports for each
+        # manager. Cache this so that the iteration only occurs one time.
+        #
+        # Returns a Hash of { "dn" => Set(Entitlements::Models::Person) }
+        Contract C::None => C::HashOf[String => C::SetOf[Entitlements::Models::Person]]
+        def direct_reports_cache
+          return @direct_reports_cache if @direct_reports_cache
+
+          Entitlements.logger.debug "Building #{self.class} direct_reports_cache"
+
+          @direct_reports_cache = {}
+          @people_hash.each do |uid, entry|
+            # If this person doesn't have a manager, then bail. (CEO)
+            next unless entry.manager && entry.manager != entry.uid
+
+            # Initialize their manager's list of direct reports if necessary, and add this person
+            # to that list.
+            person_manager_uid = entry.manager.downcase
+            @direct_reports_cache[person_manager_uid] ||= Set.new
+            @direct_reports_cache[person_manager_uid].add entry
+          end
+
+          Entitlements.logger.debug "Built #{self.class} direct_reports_cache"
+
+          @direct_reports_cache
+        end
+
+        # Iterate through the list of managers and build up the lists of direct and indirect reports for each
+        # manager. Cache this so that the iteration only occurs one time.
+        #
+        # Returns a Hash of { "dn" => Set(Entitlements::Models::Person) }
+        Contract C::None => C::HashOf[String => C::SetOf[Entitlements::Models::Person]]
+        def all_reports_cache
+          return @all_reports_cache if @all_reports_cache
+
+          Entitlements.logger.debug "Building #{self.class} all_reports_cache"
+
+          @all_reports_cache = {}
+          direct_reports_cache.keys.each do |manager_uid|
+            generate_recursive_reports(manager_uid.downcase)
+          end
+
+          Entitlements.logger.debug "Built #{self.class} all_reports_cache"
+
+          @all_reports_cache
+        end
+
+        # Recursive method to determine all reports (direct and indirect). Intended to be called
+        # from `reports` method, when @direct_reports_cache has been populated but @all_reports_cache
+        # has not yet been initialized. This will populate @all_reports_cache. This hits each manager
+        # only once - O(N).
+        #
+        # manager_uid - A String with the uid of the manager.
+        #
+        # No return value.
+        Contract String => nil
+        def generate_recursive_reports(manager_uid)
+          # If we've calculated it already, then just return early
+          return if @all_reports_cache.key?(manager_uid)
+
+          # We've visited, so start the entry for it.
+          @all_reports_cache[manager_uid] = Set.new
+
+          # Add each direct report, as well as that person's direct reports, and so on.
+          direct_reports_cache[manager_uid].each do |direct_report|
+            # The direct report is also an "all" report for their manager.
+            @all_reports_cache[manager_uid].add direct_report
+            direct_report_uid = direct_report.uid.downcase
+
+            # If the direct report has no reports of their own, no need to go any further.
+            next unless direct_reports_cache.key?(direct_report_uid)
+
+            # Call this method again, this time with the direct report as the key. If we've already
+            # calculated all descendant reports of this person, it'll return immediately. Otherwise
+            # it'll iterate through this logic again, ensuring that we only calculate descendants
+            # once for any given person.
+            generate_recursive_reports(direct_report_uid)
+
+            # Merge in the calculated result for all of this report's descendants.
+            @all_reports_cache[manager_uid].merge @all_reports_cache[direct_report_uid]
+          end
+
+          # Satisfy the contract for return value.
+          nil
+        end
+      end
+    end
+  end
+end