SetupSectionSlackChannelsJob.java

package edu.ucsb.cs156.frontiers.jobs;

import edu.ucsb.cs156.frontiers.entities.Course;
import edu.ucsb.cs156.frontiers.entities.CourseStaff;
import edu.ucsb.cs156.frontiers.entities.RosterStudent;
import edu.ucsb.cs156.frontiers.entities.Section;
import edu.ucsb.cs156.frontiers.enums.RosterStatus;
import edu.ucsb.cs156.frontiers.errors.SlackApiException;
import edu.ucsb.cs156.frontiers.models.SlackChannel;
import edu.ucsb.cs156.frontiers.models.SlackUser;
import edu.ucsb.cs156.frontiers.repositories.CourseRepository;
import edu.ucsb.cs156.frontiers.repositories.CourseStaffRepository;
import edu.ucsb.cs156.frontiers.repositories.RosterStudentRepository;
import edu.ucsb.cs156.frontiers.repositories.SectionRepository;
import edu.ucsb.cs156.frontiers.services.CanvasApiTokenSecurityService;
import edu.ucsb.cs156.frontiers.services.SlackService;
import edu.ucsb.cs156.frontiers.utilities.CanonicalFormConverter;
import edu.ucsb.cs156.jobs.services.JobContext;
import edu.ucsb.cs156.jobs.services.JobContextConsumer;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.stream.StreamSupport;
import lombok.Builder;

/**
 * Makes the public Slack channels of a course's sections match the roster.
 *
 * <ol>
 *   <li>For each row of the sections table that has a Slack channel name, creates a public channel
 *       with that name, unless it already exists. (Several sections may share a channel.)
 *   <li>Adds each roster student (status ROSTER or MANUAL) to the channel of their section, unless
 *       they are already in it. Students are matched to Slack users by email; students without an
 *       active Slack account cannot be added, and are only counted, by reason (invited but not
 *       accepted yet, account deactivated, or not in the workspace).
 *   <li>Removes from each of those channels every person who is neither a roster student of one of
 *       the channel's sections, nor a member of the course staff, nor the instructor. Bots
 *       (including the bot this job acts as) and members that are not users of the workspace are
 *       never removed. Whether the bot may remove members from public channels is a workspace
 *       setting; if Slack refuses (restricted_action), the log says how to change the setting and
 *       no further removals are attempted in that run.
 * </ol>
 *
 * A problem with one channel or one person is logged, and the job carries on with the rest.
 */
@Builder
public class SetupSectionSlackChannelsJob implements JobContextConsumer {

  /** Only these roster students are considered: in particular, not dropped students. */
  public static final List<RosterStatus> ENROLLED_STATUSES =
      List.of(RosterStatus.ROSTER, RosterStatus.MANUAL);

  Course course;
  CourseRepository courseRepository;
  SectionRepository sectionRepository;
  RosterStudentRepository rosterStudentRepository;
  CourseStaffRepository courseStaffRepository;
  SlackService slackService;
  CanvasApiTokenSecurityService tokenSecurityService;

  @Override
  public String getScopeType() {
    return "course";
  }

  @Override
  public Long getScopeId() {
    return course.getId();
  }

  @Override
  public void accept(JobContext ctx) throws Exception {
    Course currentCourse = courseRepository.findById(course.getId()).orElseThrow();
    String token = tokenSecurityService.decrypt(currentCourse.getSlackBotToken());
    if (token == null || token.isEmpty()) {
      throw new IllegalStateException(
          "No Slack token has been set for this course; enter one on the Settings tab.");
    }

    List<SlackUser> slackUsers = slackService.listUsers(token);
    Map<String, SlackUser> slackUsersById = new HashMap<>();
    Map<String, String> activeSlackIdByEmail = new HashMap<>();
    // For people whose account is not active: true if they have been invited but have not accepted
    // yet, false if their account has been deactivated. As on the Slack tab, an invitation wins
    // over a deactivated account with the same email.
    Map<String, Boolean> invitedByEmail = new HashMap<>();
    for (SlackUser user : slackUsers) {
      slackUsersById.put(user.getId(), user);
      if (user.isActivePerson() && user.email() != null) {
        activeSlackIdByEmail.put(canonical(user.email()), user.getId());
      } else if (user.isPerson() && user.email() != null) {
        invitedByEmail.merge(canonical(user.email()), !user.getDeleted(), Boolean::logicalOr);
      }
    }
    if (activeSlackIdByEmail.isEmpty()) {
      // Without emails nobody can be matched, and everybody would be removed from the channels.
      throw new IllegalStateException(
          "Slack did not provide the email of any user. Add the users:read.email scope to the Slack app, reinstall it to the workspace, and save the new token on the Settings tab.");
    }

    ctx.log("Creating Section Channels");
    Map<String, Set<String>> sectionsByChannelName = sectionsByChannelName(currentCourse.getId());
    Map<String, List<String>> channelNamesBySection = channelNamesBySection(sectionsByChannelName);
    Map<String, String> channelIdByName =
        createChannels(ctx, token, sectionsByChannelName.keySet());

    List<RosterStudent> students = enrolledStudents(currentCourse.getId());
    Set<String> staffSlackIds = staffSlackIds(currentCourse, activeSlackIdByEmail);

    // Members of each channel before this job changes anything; null if they could not be listed
    Map<String, List<String>> membersByChannelName = new HashMap<>();
    // Slack ids of the students that belong in each channel
    Map<String, Set<String>> studentSlackIdsByChannelName = new HashMap<>();

    ctx.log("Adding Students to Channel");
    int studentsInvited = 0;
    int studentsDeactivated = 0;
    int studentsNotInWorkspace = 0;
    for (RosterStudent student : students) {
      List<String> matchingChannels =
          channelNamesBySection.getOrDefault(student.getSection(), List.of());
      if (matchingChannels.isEmpty()) {
        ctx.log(
            "Student %s is in untranslated roster section %s"
                .formatted(describe(student), describeSection(student.getSection())));
        ctx.log(
            "Could not add %s to a section Slack channel because no configured channel matches untranslated roster section %s."
                .formatted(describe(student), describeSection(student.getSection())));
      } else {
        ctx.log(
            "Student %s is in untranslated roster section %s and maps to %s"
                .formatted(
                    describe(student),
                    describeSection(student.getSection()),
                    describeChannelNames(matchingChannels)));
      }
    }
    for (Map.Entry<String, String> channel : channelIdByName.entrySet()) {
      String channelName = channel.getKey();
      String channelId = channel.getValue();
      List<String> members;
      try {
        members = slackService.listChannelMembers(token, channelId);
      } catch (SlackApiException e) {
        ctx.log("Error listing members of #%s: %s".formatted(channelName, e.getMessage()));
        continue;
      }
      membersByChannelName.put(channelName, members);

      Set<String> studentSlackIds = new HashSet<>();
      List<RosterStudent> toAdd = new ArrayList<>();
      for (RosterStudent student : students) {
        if (sectionsByChannelName.get(channelName).contains(student.getSection())) {
          String slackId =
              student.getEmail() == null
                  ? null
                  : activeSlackIdByEmail.get(canonical(student.getEmail()));
          if (slackId == null) {
            Boolean invited =
                student.getEmail() == null
                    ? null
                    : invitedByEmail.get(canonical(student.getEmail()));
            if (invited == null) {
              studentsNotInWorkspace++;
            } else if (invited) {
              studentsInvited++;
            } else {
              studentsDeactivated++;
            }
          } else {
            studentSlackIds.add(slackId);
            if (!members.contains(slackId)) {
              toAdd.add(student);
            }
          }
        }
      }
      studentSlackIdsByChannelName.put(channelName, studentSlackIds);
      addStudents(ctx, token, channelName, channelId, toAdd, activeSlackIdByEmail);
    }
    // Students who cannot be added are not logged one by one (the Slack tab lists them), but the
    // log does say why: most often, they have not accepted their invitation yet.
    List<String> reasons = new ArrayList<>();
    if (studentsInvited > 0) {
      reasons.add(
          "%d invited to the Slack workspace but not accepted yet".formatted(studentsInvited));
    }
    if (studentsDeactivated > 0) {
      reasons.add("%d with a deactivated Slack account".formatted(studentsDeactivated));
    }
    if (studentsNotInWorkspace > 0) {
      reasons.add("%d not in the Slack workspace".formatted(studentsNotInWorkspace));
    }
    if (!reasons.isEmpty()) {
      ctx.log(
          "%d student(s) in these sections could not be added: %s. See the Slack tab. Run this job again once they have joined."
              .formatted(
                  studentsInvited + studentsDeactivated + studentsNotInWorkspace,
                  String.join(", ", reasons)));
    }

    ctx.log("Removing Channel Members Who Are Not In The Section");
    channels:
    for (Map.Entry<String, String> channel : channelIdByName.entrySet()) {
      String channelName = channel.getKey();
      List<String> members = membersByChannelName.get(channelName);
      if (members == null) {
        continue;
      }
      for (String memberId : members) {
        SlackUser member = slackUsersById.get(memberId);
        boolean belongs =
            staffSlackIds.contains(memberId)
                || studentSlackIdsByChannelName.get(channelName).contains(memberId);
        // Bots (including this one) and members who are not users of the workspace are left alone
        if (!belongs && member != null && member.isPerson()) {
          try {
            slackService.removeFromChannel(token, channel.getValue(), memberId);
            ctx.log("Removed %s from #%s".formatted(describe(member), channelName));
          } catch (SlackApiException e) {
            ctx.log(
                "Error removing %s from #%s: %s"
                    .formatted(describe(member), channelName, e.getMessage()));
            if (SlackService.RESTRICTED_ACTION.equals(e.getMessage())) {
              // A workspace setting forbids it, so every other removal would fail the same way
              ctx.log(SlackService.REMOVAL_RESTRICTED_ADVICE);
              break channels;
            }
          }
        }
      }
    }
    ctx.log("Done");
  }

  /**
   * @return for each (normalized) channel name, in order of section, the sections that use it
   */
  private Map<String, Set<String>> sectionsByChannelName(Long courseId) {
    Map<String, Set<String>> result = new LinkedHashMap<>();
    for (Section section : sectionRepository.findByCourseIdOrderBySectionAsc(courseId)) {
      String channelName = normalizeChannelName(section.getSlackChannelName());
      if (!channelName.isEmpty()) {
        result.computeIfAbsent(channelName, name -> new HashSet<>()).add(section.getSection());
      }
    }
    return result;
  }

  private Map<String, List<String>> channelNamesBySection(
      Map<String, Set<String>> sectionsByChannelName) {
    Map<String, List<String>> result = new HashMap<>();
    for (Map.Entry<String, Set<String>> entry : sectionsByChannelName.entrySet()) {
      for (String section : entry.getValue()) {
        result.computeIfAbsent(section, unused -> new ArrayList<>()).add(entry.getKey());
      }
    }
    return result;
  }

  private List<RosterStudent> enrolledStudents(Long courseId) {
    return StreamSupport.stream(
            rosterStudentRepository
                .findByCourseIdOrderByFirstNameAscLastNameAscIgnoreCase(courseId)
                .spliterator(),
            false)
        .filter(student -> ENROLLED_STATUSES.contains(student.getRosterStatus()))
        .toList();
  }

  /**
   * Slack channel names are lowercase, and are written with a leading # that is not part of the
   * name.
   *
   * @param name the name as entered for the section; may be null
   * @return the name to use with the Slack API, or an empty string if there is none
   */
  public static String normalizeChannelName(String name) {
    if (name == null) {
      return "";
    }
    String stripped = name.strip();
    if (stripped.startsWith("#")) {
      stripped = stripped.substring(1).strip();
    }
    return stripped.toLowerCase(Locale.ROOT);
  }

  /**
   * Creates the channels that do not exist yet, and makes the bot a member of the ones that do.
   *
   * @return the id of each channel that is ready to be used, by name
   */
  private Map<String, String> createChannels(
      JobContext ctx, String token, Set<String> channelNames) {
    Map<String, SlackChannel> existingByName = new HashMap<>();
    for (SlackChannel existing : slackService.listPublicChannels(token)) {
      existingByName.put(existing.getName(), existing);
    }

    Map<String, String> channelIdByName = new LinkedHashMap<>();
    for (String channelName : channelNames) {
      SlackChannel existing = existingByName.get(channelName);
      try {
        if (existing == null) {
          SlackChannel created = slackService.createPublicChannel(token, channelName);
          channelIdByName.put(channelName, created.getId());
          ctx.log("Created channel #%s".formatted(channelName));
        } else if (existing.getArchived()) {
          ctx.log(
              "Channel #%s already exists, but is archived; unarchive it in Slack, then run this job again. Skipping it."
                  .formatted(channelName));
        } else {
          slackService.joinChannel(token, existing.getId());
          channelIdByName.put(channelName, existing.getId());
          ctx.log("Channel #%s already exists".formatted(channelName));
        }
      } catch (SlackApiException e) {
        ctx.log(
            "Error setting up channel #%s: %s. Skipping it."
                .formatted(channelName, e.getMessage()));
      }
    }
    return channelIdByName;
  }

  /**
   * Adds the students with one call to Slack. Slack adds all or none, so if that fails, they are
   * added one at a time, so that one problem student does not keep the others out.
   */
  private void addStudents(
      JobContext ctx,
      String token,
      String channelName,
      String channelId,
      List<RosterStudent> toAdd,
      Map<String, String> activeSlackIdByEmail) {
    if (toAdd.isEmpty()) {
      return;
    }
    List<String> slackIds = new ArrayList<>();
    for (RosterStudent student : toAdd) {
      slackIds.add(activeSlackIdByEmail.get(canonical(student.getEmail())));
    }
    try {
      slackService.inviteToChannel(token, channelId, slackIds);
      for (RosterStudent student : toAdd) {
        ctx.log("Added %s to #%s".formatted(describe(student), channelName));
      }
      return;
    } catch (SlackApiException e) {
      ctx.log(
          "Could not add %d student(s) to #%s in one step (%s); adding them one at a time."
              .formatted(toAdd.size(), channelName, e.getMessage()));
    }
    for (int i = 0; i < toAdd.size(); i++) {
      try {
        slackService.inviteToChannel(token, channelId, List.of(slackIds.get(i)));
        ctx.log("Added %s to #%s".formatted(describe(toAdd.get(i)), channelName));
      } catch (SlackApiException e) {
        ctx.log(
            "Error adding %s to #%s: %s"
                .formatted(describe(toAdd.get(i)), channelName, e.getMessage()));
      }
    }
  }

  /** Slack ids of the staff of the course and of its instructor, who belong in every channel. */
  private Set<String> staffSlackIds(Course currentCourse, Map<String, String> slackIdByEmail) {
    Set<String> result = new HashSet<>();
    for (CourseStaff staff : courseStaffRepository.findByCourseId(currentCourse.getId())) {
      if (staff.getEmail() != null) {
        // null (staff member not in Slack) is harmless in this set: no channel member has id null
        result.add(slackIdByEmail.get(canonical(staff.getEmail())));
      }
    }
    if (currentCourse.getInstructorEmail() != null) {
      result.add(slackIdByEmail.get(canonical(currentCourse.getInstructorEmail())));
    }
    return result;
  }

  private static String describe(RosterStudent student) {
    return "%s %s (%s)"
        .formatted(student.getFirstName(), student.getLastName(), student.getEmail());
  }

  private static String describe(SlackUser user) {
    return "%s (%s)".formatted(user.getRealName(), user.email());
  }

  private static String describeSection(String section) {
    return section == null ? "(blank)" : section;
  }

  private static String describeChannelNames(List<String> channelNames) {
    return "#" + String.join(", #", channelNames);
  }

  private static String canonical(String email) {
    return CanonicalFormConverter.convertToValidEmail(email.strip());
  }
}