entitlements-github-plugin 0.0.1

data/lib/entitlements/backend/github_org/service.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "../../service/github"
+
+module Entitlements
+  class Backend
+    class GitHubOrg
+      class Service < Entitlements::Service::GitHub
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Sync the members of an organization in a given role to match the member list.
+        #
+        # implementation - An Hash of { action: :add/:remove, person: <person DN> }
+        # role           - A String with the role, matching a key of Entitlements::Backend::GitHubOrg::ORGANIZATION_ROLES.
+        #
+        # Returns true if it succeeded, false if it did not.
+        Contract C::ArrayOf[{ action: C::Or[:add, :remove], person: String }], String => C::Bool
+        def sync(implementation, role)
+          added_members = []
+          removed_members = []
+
+          implementation.each do |instruction|
+            username = Entitlements::Util::Util.first_attr(instruction[:person]).downcase
+            if instruction[:action] == :add
+              added_members << username if add_user_to_organization(username, role)
+            else
+              removed_members << username if remove_user_from_organization(username)
+            end
+          end
+
+          Entitlements.logger.debug "sync(#{role}): Added #{added_members.count}, removed #{removed_members.count}"
+          added_members.any? || removed_members.any?
+        end
+
+        private
+
+        # Upsert a user with a role to the organization.
+        #
+        # user: A String with the (GitHub) username of the person to add or modify.
+        # role: A String with the role, matching a key of Entitlements::Backend::GitHubOrg::ORGANIZATION_ROLES.
+        #
+        # Returns true if the user was added to the organization, false otherwise.
+        Contract String, String => C::Bool
+        def add_user_to_organization(user, role)
+          Entitlements.logger.debug "#{identifier} add_user_to_organization(user=#{user}, org=#{org}, role=#{role})"
+          new_membership = octokit.update_organization_membership(org, user: user, role: role)
+
+          # Happy path
+          if new_membership[:role] == role
+            if new_membership[:state] == "pending"
+              pending_members.add(user)
+              return true
+            elsif new_membership[:state] == "active"
+              org_members[user] = role
+              return true
+            end
+          end
+
+          Entitlements.logger.debug new_membership.inspect
+          Entitlements.logger.error "Failed to adjust membership for #{user} in organization #{org} with role #{role}!"
+          false
+        end
+
+        # Remove a user from the organization.
+        #
+        # user: A String with the (GitHub) username of the person to remove.
+        #
+        # Returns true if the user was removed, false otherwise.
+        Contract String => C::Bool
+        def remove_user_from_organization(user)
+          Entitlements.logger.debug "#{identifier} remove_user_from_organization(user=#{user}, org=#{org})"
+          result = octokit.remove_organization_membership(org, user: user)
+
+          # If we removed the user, remove them from the cache of members, so that any GitHub team
+          # operations in this organization will ignore this user.
+          if result
+            org_members.delete(user)
+            pending_members.delete(user)
+          end
+
+          # Return the result, true or false
+          result
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/backend/github_org.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Backend
+    class GitHubOrg
+      include ::Contracts::Core
+      C = ::Contracts
+
+      # There are certain supported roles (which are mutually exclusive): admin, billing manager, member.
+      # Define these in this one central place to be consumed everywhere.
+      # The key is the name of the Entitlement, and that data is how this role appears on dotcom.
+      ORGANIZATION_ROLES = {
+        "admin"  => "ADMIN",
+        # `billing-manager` is currently not supported
+        "member" => "MEMBER"
+      }
+
+      # Error classes
+      class DuplicateUserError < RuntimeError; end
+    end
+  end
+end
+
+require_relative "github_org/controller"
+require_relative "github_org/provider"
+require_relative "github_org/service"

data/lib/entitlements/backend/github_team/controller.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Backend
+    class GitHubTeam
+      class Controller < Entitlements::Backend::BaseController
+        # Controller priority and registration
+        def self.priority
+          40
+        end
+
+        register
+
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Constructor. Generic constructor that takes a hash of configuration options.
+        #
+        # group_name - Name of the corresponding group in the entitlements configuration file.
+        # config     - Optionally, a Hash of configuration information (configuration is referenced if empty).
+        Contract String, C::Maybe[C::HashOf[String => C::Any]] => C::Any
+        def initialize(group_name, config = nil)
+          super
+          @provider = Entitlements::Backend::GitHubTeam::Provider.new(config: @config)
+        end
+
+        def prefetch
+          teams = Entitlements::Data::Groups::Calculated.read_all(group_name, config)
+          teams.each do |team_slug|
+            entitlement_group = Entitlements::Data::Groups::Calculated.read(team_slug)
+            provider.read(entitlement_group)
+          end
+        end
+
+        # Calculation routines.
+        #
+        # Takes no arguments.
+        #
+        # Returns a list of @actions.
+        Contract C::None => C::Any
+        def calculate
+          added = []
+          changed = []
+          teams = Entitlements::Data::Groups::Calculated.read_all(group_name, config)
+          teams.each do |team_slug|
+            group = Entitlements::Data::Groups::Calculated.read(team_slug)
+
+            # Anyone who is not a member of the organization is ignored in the diff calculation.
+            # This avoids adding an organization membership for someone by virtue of adding them
+            # to a team, without declaring them as an administrator or a member of the org. Also
+            # this avoids having a pending member show up in diffs until they accept their invite.
+            ignored_users = provider.auto_generate_ignored_users(group)
+
+            # "diff" includes a call to GitHub API to read the team as it currently exists there.
+            # Returns a hash { added: Set(members), removed: Set(members) }
+            diff = provider.diff(group, ignored_users)
+
+            if diff[:added].empty? && diff[:removed].empty? && diff[:metadata].nil?
+              logger.debug "UNCHANGED: No GitHub team changes for #{group_name}:#{team_slug}"
+              next
+            end
+
+            if diff[:metadata] && diff[:metadata][:create_team]
+              added << Entitlements::Models::Action.new(team_slug, provider.read(group), group, group_name, ignored_users: ignored_users)
+            else
+              changed << Entitlements::Models::Action.new(team_slug, provider.read(group), group, group_name, ignored_users: ignored_users)
+            end
+          end
+          print_differences(key: group_name, added: added, removed: [], changed: changed)
+
+          @actions = added + changed
+        end
+
+        # Apply changes.
+        #
+        # action - Action array.
+        #
+        # Returns nothing.
+        Contract Entitlements::Models::Action => C::Any
+        def apply(action)
+          unless action.updated.is_a?(Entitlements::Models::Group)
+            logger.fatal "#{action.dn}: GitHub entitlements interface does not support removing a team at this point"
+            raise RuntimeError, "Invalid Operation"
+          end
+
+          if provider.change_ignored?(action)
+            logger.debug "SKIP: GitHub team #{action.dn} only changes organization non-members or pending members"
+            return
+          end
+
+          if provider.commit(action.updated)
+            logger.debug "APPLY: Updating GitHub team #{action.dn}"
+          else
+            logger.warn "DID NOT APPLY: Changes not needed to #{action.dn}"
+            logger.debug "Old: #{action.existing.inspect}"
+            logger.debug "New: #{action.updated.inspect}"
+          end
+        end
+
+        # Validate configuration options.
+        #
+        # key  - String with the name of the group.
+        # data - Hash with the configuration data.
+        #
+        # Returns nothing.
+        # :nocov:
+        Contract String, C::HashOf[String => C::Any] => nil
+        def validate_config!(key, data)
+          spec = COMMON_GROUP_CONFIG.merge({
+            "base"  => { required: true, type: String },
+            "addr"  => { required: false, type: String },
+            "org"   => { required: true, type: String },
+            "token" => { required: true, type: String }
+          })
+          text = "GitHub group #{key.inspect}"
+          Entitlements::Util::Util.validate_attr!(spec, data, text)
+        end
+        # :nocov:
+
+        private
+
+        attr_reader :provider
+      end
+    end
+  end
+end

data/lib/entitlements/backend/github_team/models/team.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Backend
+    class GitHubTeam
+      class Models
+        class Team < Entitlements::Models::Group
+          include ::Contracts::Core
+          C = ::Contracts
+
+          attr_reader :team_id, :team_name, :team_dn
+
+          # Constructor.
+          #
+          # team_id   - Integer with the team ID
+          # team_name - String with the team name
+          # members   - Set of String with member UID
+          # ou        - A String with the base OU
+          Contract C::KeywordArgs[
+            team_id: Integer,
+            team_name: String,
+            members: C::SetOf[String],
+            ou: String,
+            metadata: C::Or[C::HashOf[String => C::Any], nil]
+          ] => C::Any
+          def initialize(team_id:, team_name:, members:, ou:, metadata:)
+            @team_id = team_id
+            @team_name = team_name.downcase
+            @team_dn = ["cn=#{team_name.downcase}", ou].join(",")
+            super(dn: @team_dn, members: Set.new(members.map { |m| m.downcase }), metadata: metadata)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/backend/github_team/provider.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "service"
+
+require "set"
+require "uri"
+
+module Entitlements
+  class Backend
+    class GitHubTeam
+      class Provider < Entitlements::Backend::BaseProvider
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Constructor.
+        #
+        # config - Configuration provided for the controller instantiation
+        Contract C::KeywordArgs[
+          config: C::HashOf[String => C::Any],
+        ] => C::Any
+        def initialize(config:)
+          @github = Entitlements::Backend::GitHubTeam::Service.new(
+            org: config.fetch("org"),
+            addr: config.fetch("addr", nil),
+            token: config.fetch("token"),
+            ou: config.fetch("base")
+          )
+
+          @github_team_cache = {}
+        end
+
+        # Read in a specific GitHub.com Team and enumerate its members. Results are cached
+        # for future runs.
+        #
+        # team_identifier - Entitlements::Models::Group representing the entitlement
+        #
+        # Returns a Entitlements::Models::Group object representing the GitHub group or nil if the GitHub.com Team does not exist
+        Contract Entitlements::Models::Group => C::Maybe[Entitlements::Models::Group]
+        def read(entitlement_group)
+          slug = Entitlements::Util::Util.any_to_cn(entitlement_group.cn.downcase)
+          return @github_team_cache[slug] if @github_team_cache[slug]
+
+          github_team = github.read_team(entitlement_group)
+
+          # We should not cache a team which does not exist
+          return nil if github_team.nil?
+
+          Entitlements.logger.debug "Loaded #{github_team.team_dn} (id=#{github_team.team_id}) with #{github_team.member_strings.count} member(s)"
+          @github_team_cache[github_team.team_name] = github_team
+        end
+
+        # Dry run of committing changes. Returns a list of users added or removed.
+        #
+        # group - An Entitlements::Models::Group object.
+        #
+        # Returns added / removed hash.
+        Contract Entitlements::Models::Group, C::Maybe[C::SetOf[String]] => Hash[added: C::SetOf[String], removed: C::SetOf[String]]
+        def diff(entitlement_group, ignored_users = Set.new)
+          # The current value of the team from `read` might be based on the predictive cache
+          # or on an actual API call. At this stage we don't care.
+          team_identifier = entitlement_group.cn.downcase
+          github_team_group = read(entitlement_group)
+          if github_team_group.nil?
+            github_team_group = create_github_team_group(entitlement_group)
+          end
+
+          result = diff_existing_updated(github_team_group, entitlement_group, ignored_users)
+
+          # If there are no differences, return. (If we read from the predictive cache, we just saved ourselves a call
+          # to the API. Hurray.)
+          return result unless result[:added].any? || result[:removed].any? || result[:metadata]
+
+          # If the group doesn't exist yet, we know we're not using the cache and we can save on any further API calls
+          unless github_team_group.metadata_fetch_if_exists("team_id") == -999
+            # There are differences so we don't want to use the predictive cache. Call to `from_predictive_cache?`
+            # to determine whether our source of "current state" came from the predictive cache or from the API.
+            # If it returns false, it came from the API, and we should just return what we got
+            # (since pulling the data from the API again would be pointless).
+            return result unless github.from_predictive_cache?(entitlement_group)
+
+            # If `from_predictive_cache?` returned true, the data came from the predictive cache. We need
+            # to invalidate the predictive cache entry, clean up the instance variable and re-read the refreshed data.
+            github.invalidate_predictive_cache(entitlement_group)
+            @github_team_cache.delete(team_identifier)
+            github_team_group = read(entitlement_group)
+          end
+
+          # And finally, we have to calculate a new diff, which this time uses the fresh data from the API as
+          # its basis, rather than the predictive cache.
+          diff_existing_updated(github_team_group, entitlement_group, ignored_users)
+        end
+
+        # Dry run of committing changes. Returns a list of users added or removed and a hash explaining metadata changes
+        # Takes an existing and an updated group object, avoiding a lookup in the backend.
+        #
+        # existing_group - An Entitlements::Models::Group object.
+        # group          - An Entitlements::Models::Group object.
+        # ignored_users  - Optionally, a Set of lower-case Strings of users to ignore.
+        Contract Entitlements::Models::Group, Entitlements::Models::Group, C::Maybe[C::SetOf[String]] => Hash[added: C::SetOf[String], removed: C::SetOf[String], metadata: C::Maybe[Hash[]]]
+        def diff_existing_updated(existing_group, group, ignored_users = Set.new)
+          diff_existing_updated_metadata(existing_group, group, super)
+        end
+
+        # Determine if a change needs to be ignored. This will return true if the
+        # user being added or removed is ignored.
+        #
+        # action - Entitlements::Models::Action object
+        #
+        # Returns true if the change should be ignored, false otherwise.
+        Contract Entitlements::Models::Action => C::Bool
+        def change_ignored?(action)
+          return false if action.existing.nil?
+
+          result = diff_existing_updated(action.existing, action.updated, action.ignored_users)
+          result[:added].empty? && result[:removed].empty? && result[:metadata].nil?
+        end
+
+        # Commit changes.
+        #
+        # group - An Entitlements::Models::Group object.
+        #
+        # Returns true if a change was made, false if no change was made.
+        Contract Entitlements::Models::Group => C::Bool
+        def commit(entitlement_group)
+          github_team = github.read_team(entitlement_group)
+
+          # Create the new team and invalidate the cache
+          if github_team.nil?
+            team_name = entitlement_group.cn.downcase
+            github.create_team(entitlement_group: entitlement_group)
+            github.invalidate_predictive_cache(entitlement_group)
+            @github_team_cache.delete(team_name)
+            github_team = github.read_team(entitlement_group)
+          end
+          github.sync_team(entitlement_group, github_team)
+        end
+
+        # Automatically generate ignored users for a group. Find all members listed in the group who are not
+        # admins or members of the GitHub organization in question.
+        #
+        # group - An Entitlements::Models::Group object.
+        #
+        # Returns a set of strings with usernames meeting the criteria.
+        Contract Entitlements::Models::Group => C::SetOf[String]
+        def auto_generate_ignored_users(entitlement_group)
+          org_members = github.org_members.keys.map(&:downcase)
+          group_members = entitlement_group.member_strings.map(&:downcase)
+          Set.new(group_members - org_members)
+        end
+
+        private
+
+        # Construct an Entitlements::Models::Group for a new group and team
+        #
+        # group - An Entitlements::Models::Group object representing the defined group
+        #
+        # Returns an Entitlements::Models::Group for a new group
+        Contract Entitlements::Models::Group => Entitlements::Models::Group
+        def create_github_team_group(entitlement_group)
+          begin
+            metadata = entitlement_group.metadata
+            metadata["team_id"] = -999
+          rescue Entitlements::Models::Group::NoMetadata
+            metadata = {"team_id" => -999}
+          end
+          Entitlements::Backend::GitHubTeam::Models::Team.new(
+            team_id: -999,
+            team_name: entitlement_group.cn.downcase,
+            members: Set.new,
+            ou: github.ou,
+            metadata: metadata
+          )
+        end
+
+        # Returns a diff hash of group metadata
+        # Takes an existing and an updated group object, avoiding a lookup in the backend.
+        #
+        # existing_group - An Entitlements::Models::Group object.
+        # group          - An Entitlements::Models::Group object.
+        # base_diff  - Hash representing the base diff from diff_existing_updated
+        Contract Entitlements::Models::Group, Entitlements::Models::Group, Hash[added: C::SetOf[String], removed: C::SetOf[String], metadata: C::Or[Hash[], nil]] => Hash[added: C::SetOf[String], removed: C::SetOf[String], metadata: C::Or[Hash[], nil]]
+        def diff_existing_updated_metadata(existing_group, group, base_diff)
+          if existing_group.metadata_fetch_if_exists("team_id") == -999
+            base_diff[:metadata] = { create_team: true }
+          end
+          existing_parent_team = existing_group.metadata_fetch_if_exists("parent_team_name")
+          changed_parent_team = group.metadata_fetch_if_exists("parent_team_name")
+
+          if existing_parent_team != changed_parent_team
+            if existing_parent_team.nil? && !changed_parent_team.nil?
+              base_diff[:metadata] = { parent_team: "add" }
+              Entitlements.logger.info "ADD github_parent_team #{changed_parent_team} to #{existing_group.dn} in #{github.org}"
+            elsif !existing_parent_team.nil? && changed_parent_team.nil?
+              base_diff[:metadata] = { parent_team: "remove" }
+              Entitlements.logger.info "REMOVE (NOOP) github_parent_team #{existing_parent_team} from #{existing_group.dn} in #{github.org}"
+            else
+              base_diff[:metadata] = { parent_team: "change" }
+              Entitlements.logger.info "CHANGE github_parent_team from #{existing_parent_team} to #{changed_parent_team} for #{existing_group.dn} in #{github.org}"
+            end
+          end
+          base_diff
+        end
+
+        attr_reader :github
+      end
+    end
+  end
+end