SetupPrivateSlackChannelsJob.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.enums.RosterStatus;
import edu.ucsb.cs156.frontiers.errors.SlackApiException;
import edu.ucsb.cs156.frontiers.models.SlackAuthTestResponse;
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.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.text.Normalizer;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.stream.Stream;
import lombok.Builder;

/**
 * Gives each student of a course a private Slack channel shared with the staff of the course.
 *
 * <ol>
 *   <li>For each roster student (status ROSTER or MANUAL) with an active Slack account, works out a
 *       channel name: "private-first-last" (see {@link #channelNameFor}). The first and last name
 *       come from the student's Slack profile when it has them, and otherwise from the roster; only
 *       the first word of the first name is used. Students who would get the same name also get the
 *       part of their email before the @ at the end.
 *   <li>Finds the channel each student already has. A channel is a student's if it is a private
 *       channel that this bot created, and that student is the only one of the students among its
 *       members. Channels are never recognized by name, so a channel is found again even after the
 *       name of the student has changed.
 *   <li>Creates the private channel of each student who does not have one, and renames the channel
 *       of each student whose channel does not have the name worked out in the first step.
 *   <li>Adds the student, the instructor and the staff of the course to the channel, unless they
 *       are already in it. People are matched to Slack users by email; those without an active
 *       Slack account cannot be added, and are only counted.
 *   <li>Removes from each student's channel every person who is neither the student, nor the
 *       instructor, nor a member of the course staff: for example somebody who has been deleted
 *       from the staff of the course. Bots (including the bot this job acts as) and members that
 *       are not users of the workspace are never removed. If Slack refuses because of a workspace
 *       setting (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; but if
 * the members of an existing channel cannot be listed, the job stops before changing anything,
 * since it could not tell whose channel that is and might create a duplicate. The last line of the
 * log is a summary.
 */
@Builder
public class SetupPrivateSlackChannelsJob implements JobContextConsumer {

  public static final String CHANNEL_PREFIX = "private";

  /** Slack does not allow longer channel names. */
  public static final int MAX_CHANNEL_NAME_LENGTH = 80;

  /** Slack's error code when a channel (public or private, archived or not) has the name. */
  public static final String NAME_TAKEN = "name_taken";

  /** What to tell the instructor when creating a channel fails with {@link #NAME_TAKEN}. */
  public static final String NAME_TAKEN_ADVICE =
      "Slack already has a channel named #%s, which this job does not recognize as the private channel of this student: it may be a public channel, a private channel that this bot did not create, or a private channel that does not have exactly one student of the course among its members. Rename that channel in Slack, or fix its members, then run this job again.";

  /**
   * What to tell the instructor when removing a member fails with {@link
   * SlackService#RESTRICTED_ACTION}.
   */
  public static final String REMOVAL_RESTRICTED_ADVICE =
      "Slack does not allow this bot to remove members from private channels, so no more members will be removed in this run. A Workspace Owner can change this in Slack under Workspace settings, Roles & permissions (on older workspaces: Permissions, Channel Management): set \"People who can remove members from private channels\" to \"Everyone, except guests\". Then run this job again.";

  /** 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;
  RosterStudentRepository rosterStudentRepository;
  CourseStaffRepository courseStaffRepository;
  SlackService slackService;
  CanvasApiTokenSecurityService tokenSecurityService;

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

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

  /**
   * Turns part of a name into the form Slack requires of channel names: accents are dropped, the
   * rest is lowercased, and each run of characters other than letters, numbers and underscores is
   * replaced by one hyphen (none at the start or the end).
   *
   * @param namePart for example a last name; may be null
   * @return the sanitized name part; empty if nothing is left
   */
  public static String sanitize(String namePart) {
    if (namePart == null) {
      return "";
    }
    return Normalizer.normalize(namePart, Normalizer.Form.NFD)
        .replaceAll("\\p{M}", "")
        .toLowerCase(Locale.ROOT)
        .replaceAll("[^a-z0-9_]+", "-")
        .replaceAll("^-|-$", "");
  }

  /**
   * @param firstName a first name, possibly followed by middle names; may be null
   * @return the first name up to the first space
   */
  public static String firstWord(String firstName) {
    if (firstName == null) {
      return "";
    }
    return firstName.strip().split("\\s+")[0];
  }

  /**
   * @param firstName the first name; only the part up to the first space is used
   * @param lastName the last name
   * @param suffix added at the end, to tell apart students with the same name; may be empty
   * @return the name of the student's private Slack channel, for example private-chris-gaucho
   */
  public static String channelNameFor(String firstName, String lastName, String suffix) {
    String name =
        String.join(
            "-",
            Stream.of(CHANNEL_PREFIX, sanitize(firstWord(firstName)), sanitize(lastName), suffix)
                .filter(part -> !part.isEmpty())
                .toList());
    return name.substring(0, Math.min(name.length(), MAX_CHANNEL_NAME_LENGTH));
  }

  /** A student who has an active Slack account, and so gets a channel. */
  private static class StudentChannel {
    RosterStudent student;
    String firstName;
    String lastName;
    String channelName;
    // the channel the student already has, if any, and its members
    SlackChannel existing;
    List<String> members = List.of();
  }

  /** The counts reported at the end of the log. */
  private static class Summary {
    int channelsCreated;
    int channelsExisting;
    int channelsRenamed;
    int membersAdded;
    int membersAlreadyPresent;
    int membersRemoved;
    // set once Slack has refused a removal because of a workspace setting
    boolean removalsRestricted;
  }

  @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.");
    }

    Map<String, SlackUser> slackUsersById = new HashMap<>();
    Map<String, SlackUser> activeSlackUserByEmail = new HashMap<>();
    for (SlackUser user : slackService.listUsers(token)) {
      slackUsersById.put(user.getId(), user);
      if (user.isActivePerson() && user.email() != null) {
        activeSlackUserByEmail.put(canonical(user.email()), user);
      }
    }
    if (activeSlackUserByEmail.isEmpty()) {
      // Without emails nobody can be matched to a Slack user.
      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.");
    }

    // The instructor and the staff, who belong in every channel: Slack id, and a label for the log
    Map<String, String> staff = new LinkedHashMap<>();
    int staffNotInSlack = 0;
    if (currentCourse.getInstructorEmail() != null) {
      SlackUser instructor =
          activeSlackUserByEmail.get(canonical(currentCourse.getInstructorEmail()));
      if (instructor == null) {
        staffNotInSlack++;
      } else {
        staff.put(instructor.getId(), "instructor " + currentCourse.getInstructorEmail());
      }
    }
    for (CourseStaff staffMember : courseStaffRepository.findByCourseId(currentCourse.getId())) {
      SlackUser slackUser =
          staffMember.getEmail() == null
              ? null
              : activeSlackUserByEmail.get(canonical(staffMember.getEmail()));
      if (slackUser == null) {
        staffNotInSlack++;
      } else {
        staff.putIfAbsent(slackUser.getId(), "staff member " + staffMember.getEmail());
      }
    }

    // The students who get a channel, by Slack id
    Map<String, StudentChannel> students = new LinkedHashMap<>();
    int studentsNotInSlack = 0;
    List<String> studentsOnStaff = new ArrayList<>();
    for (RosterStudent student :
        rosterStudentRepository
            .findByCourseIdAndRosterStatusInOrderByFirstNameAscLastNameAscIgnoreCase(
                currentCourse.getId(), ENROLLED_STATUSES)) {
      SlackUser slackUser =
          student.getEmail() == null
              ? null
              : activeSlackUserByEmail.get(canonical(student.getEmail()));
      if (slackUser == null) {
        studentsNotInSlack++;
      } else if (staff.containsKey(slackUser.getId())) {
        // They are in every channel, so no channel could be recognized as theirs
        studentsOnStaff.add(describe(student));
      } else {
        StudentChannel studentChannel = new StudentChannel();
        studentChannel.student = student;
        studentChannel.firstName = firstNonBlank(slackUser.firstName(), student.getFirstName());
        studentChannel.lastName = firstNonBlank(slackUser.lastName(), student.getLastName());
        students.putIfAbsent(slackUser.getId(), studentChannel);
      }
    }
    chooseChannelNames(students);

    // Fails, before anything is changed, if the members of a channel cannot be listed
    findExistingChannels(token, students);

    ctx.log(
        "Creating Private Channels (%d student(s), channel names start with %s-)"
            .formatted(students.size(), CHANNEL_PREFIX));
    for (String student : studentsOnStaff) {
      ctx.log(
          "%s is also the instructor or a staff member of the course, so does not get a private channel."
              .formatted(student));
    }
    Summary summary = new Summary();
    for (Map.Entry<String, StudentChannel> entry : students.entrySet()) {
      StudentChannel studentChannel = entry.getValue();
      String channelId = setUpChannel(ctx, token, studentChannel, summary);
      if (channelId == null) {
        continue;
      }

      // who belongs, with a label for the log; the student first
      Map<String, String> belonging = new LinkedHashMap<>();
      belonging.put(entry.getKey(), describe(studentChannel.student));
      belonging.putAll(staff);
      List<Map.Entry<String, String>> toAdd = new ArrayList<>();
      for (Map.Entry<String, String> person : belonging.entrySet()) {
        if (studentChannel.members.contains(person.getKey())) {
          summary.membersAlreadyPresent++;
        } else {
          toAdd.add(person);
        }
      }
      addMembers(ctx, token, studentChannel.channelName, channelId, toAdd, summary);
      removeOthers(
          ctx, token, studentChannel, channelId, belonging.keySet(), slackUsersById, summary);
    }

    if (studentsNotInSlack > 0) {
      ctx.log(
          "%d student(s) did not get a private channel, because they do not have an active account in the Slack workspace; see the Slack tab. Run this job again once they have joined."
              .formatted(studentsNotInSlack));
    }
    if (staffNotInSlack > 0) {
      ctx.log(
          "%d staff member(s) (counting the instructor) could not be added to the channels, because they do not have an active account in the Slack workspace; see the Slack tab. Run this job again once they have joined."
              .formatted(staffNotInSlack));
    }
    ctx.log(
        "Done. Channels created: %d, already existed: %d (of which renamed: %d). Members added: %d, already present: %d, removed: %d."
            .formatted(
                summary.channelsCreated,
                summary.channelsExisting,
                summary.channelsRenamed,
                summary.membersAdded,
                summary.membersAlreadyPresent,
                summary.membersRemoved));
  }

  /**
   * Works out the name of each student's channel. Students who would get the same name are told
   * apart by the part of their email before the @.
   */
  private static void chooseChannelNames(Map<String, StudentChannel> students) {
    Map<String, Integer> timesUsed = new HashMap<>();
    for (StudentChannel studentChannel : students.values()) {
      studentChannel.channelName =
          channelNameFor(studentChannel.firstName, studentChannel.lastName, "");
      timesUsed.merge(studentChannel.channelName, 1, Integer::sum);
    }
    for (StudentChannel studentChannel : students.values()) {
      if (timesUsed.get(studentChannel.channelName) > 1) {
        studentChannel.channelName =
            channelNameFor(
                studentChannel.firstName,
                studentChannel.lastName,
                sanitize(studentChannel.student.getEmail().split("@")[0]));
      }
    }
  }

  /**
   * Finds the channel each student already has: a private channel that this bot created, in which
   * that student is the only one of the students.
   *
   * @throws IllegalStateException if the members of such a channel cannot be listed
   */
  private void findExistingChannels(String token, Map<String, StudentChannel> students) {
    SlackAuthTestResponse authTest = slackService.authTest(token);
    if (!authTest.getOk()) {
      throw new SlackApiException(String.valueOf(authTest.getError()));
    }
    for (SlackChannel channel : slackService.listPrivateChannels(token)) {
      // Only channels made by this job are considered, so that no other private channel that the
      // bot happens to have been added to is ever renamed, or opened up to the whole staff
      if (authTest.getUserId() == null || !authTest.getUserId().equals(channel.getCreator())) {
        continue;
      }
      List<String> members;
      try {
        members = slackService.listChannelMembers(token, channel.getId());
      } catch (SlackApiException e) {
        throw new IllegalStateException(
            "Could not list the members of the private channel #%s (%s), so cannot tell which student it belongs to. Nothing was changed in Slack."
                .formatted(channel.getName(), e.getMessage()));
      }
      List<String> studentMembers = members.stream().filter(students::containsKey).toList();
      if (studentMembers.size() == 1) {
        StudentChannel studentChannel = students.get(studentMembers.get(0));
        // If a student somehow has several, the one that is in use rather than archived wins
        if (studentChannel.existing == null || studentChannel.existing.getArchived()) {
          studentChannel.existing = channel;
          studentChannel.members = members;
        }
      }
    }
  }

  /**
   * Creates the student's channel, or renames the one they have if its name is not the right one.
   *
   * @return the id of the channel, or null if it is not ready to be used
   */
  private String setUpChannel(
      JobContext ctx, String token, StudentChannel studentChannel, Summary summary) {
    String channelName = studentChannel.channelName;
    String student = describe(studentChannel.student);
    SlackChannel existing = studentChannel.existing;
    if (existing == null) {
      try {
        SlackChannel created = slackService.createPrivateChannel(token, channelName);
        summary.channelsCreated++;
        ctx.log("Created private channel #%s for %s".formatted(channelName, student));
        return created.getId();
      } catch (SlackApiException e) {
        ctx.log(
            "Error creating private channel #%s for %s: %s. Skipping it."
                .formatted(channelName, student, e.getMessage()));
        if (NAME_TAKEN.equals(e.getMessage())) {
          ctx.log(NAME_TAKEN_ADVICE.formatted(channelName));
        }
        return null;
      }
    }
    if (existing.getArchived()) {
      ctx.log(
          "Private channel #%s for %s already exists, but is archived; unarchive it in Slack, then run this job again. Skipping it."
              .formatted(existing.getName(), student));
      return null;
    }
    summary.channelsExisting++;
    if (channelName.equals(existing.getName())) {
      ctx.log("Private channel #%s for %s already exists".formatted(channelName, student));
      return existing.getId();
    }
    try {
      slackService.renameChannel(token, existing.getId(), channelName);
      summary.channelsRenamed++;
      ctx.log(
          "Renamed private channel #%s to #%s for %s"
              .formatted(existing.getName(), channelName, student));
    } catch (SlackApiException e) {
      ctx.log(
          "Error renaming private channel #%s to #%s for %s: %s. It keeps its name."
              .formatted(existing.getName(), channelName, student, e.getMessage()));
      studentChannel.channelName = existing.getName();
    }
    return existing.getId();
  }

  /**
   * Adds the people 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 person does not keep the others out.
   *
   * @param toAdd Slack id and description of each person to add
   */
  private void addMembers(
      JobContext ctx,
      String token,
      String channelName,
      String channelId,
      List<Map.Entry<String, String>> toAdd,
      Summary summary) {
    if (toAdd.isEmpty()) {
      return;
    }
    List<String> slackIds = toAdd.stream().map(Map.Entry::getKey).toList();
    try {
      slackService.inviteToChannel(token, channelId, slackIds);
      for (Map.Entry<String, String> person : toAdd) {
        summary.membersAdded++;
        ctx.log("Added %s to #%s".formatted(person.getValue(), channelName));
      }
      return;
    } catch (SlackApiException e) {
      ctx.log(
          "Could not add %d member(s) to #%s in one step (%s); adding them one at a time."
              .formatted(toAdd.size(), channelName, e.getMessage()));
    }
    for (Map.Entry<String, String> person : toAdd) {
      try {
        slackService.inviteToChannel(token, channelId, List.of(person.getKey()));
        summary.membersAdded++;
        ctx.log("Added %s to #%s".formatted(person.getValue(), channelName));
      } catch (SlackApiException e) {
        ctx.log(
            "Error adding %s to #%s: %s".formatted(person.getValue(), channelName, e.getMessage()));
      }
    }
  }

  /**
   * Removes from the channel everybody who does not belong in it, such as somebody who is no longer
   * on the staff of the course. Bots (including this one) and members who are not users of the
   * workspace are left alone.
   *
   * @param belonging Slack ids of the student, the instructor and the staff
   */
  private void removeOthers(
      JobContext ctx,
      String token,
      StudentChannel studentChannel,
      String channelId,
      Set<String> belonging,
      Map<String, SlackUser> slackUsersById,
      Summary summary) {
    String channelName = studentChannel.channelName;
    for (String memberId : studentChannel.members) {
      SlackUser member = slackUsersById.get(memberId);
      if (summary.removalsRestricted
          || belonging.contains(memberId)
          || member == null
          || !member.isPerson()) {
        continue;
      }
      try {
        slackService.removeFromChannel(token, channelId, memberId);
        summary.membersRemoved++;
        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(REMOVAL_RESTRICTED_ADVICE);
          summary.removalsRestricted = true;
        }
      }
    }
  }

  private static String firstNonBlank(String preferred, String fallback) {
    return preferred == null || preferred.isBlank() ? fallback : preferred;
  }

  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 canonical(String email) {
    return CanonicalFormConverter.convertToValidEmail(email.strip());
  }
}