AssignmentsController.java

package edu.ucsb.cs156.frontiers.controllers;

import edu.ucsb.cs156.frontiers.entities.Assignment;
import edu.ucsb.cs156.frontiers.entities.Course;
import edu.ucsb.cs156.frontiers.enums.AssignmentType;
import edu.ucsb.cs156.frontiers.enums.Permission;
import edu.ucsb.cs156.frontiers.enums.RepositoryCreationOption;
import edu.ucsb.cs156.frontiers.enums.RepositoryPermissions;
import edu.ucsb.cs156.frontiers.enums.Visibility;
import edu.ucsb.cs156.frontiers.errors.EntityNotFoundException;
import edu.ucsb.cs156.frontiers.errors.NoLinkedOrganizationException;
import edu.ucsb.cs156.frontiers.jobs.CreateStudentOrStaffRepositoriesJob;
import edu.ucsb.cs156.frontiers.jobs.CreateTeamRepositoriesJob;
import edu.ucsb.cs156.frontiers.models.AssignmentWithJob;
import edu.ucsb.cs156.frontiers.repositories.AssignmentRepository;
import edu.ucsb.cs156.frontiers.repositories.CourseRepository;
import edu.ucsb.cs156.frontiers.services.GithubTeamService;
import edu.ucsb.cs156.frontiers.services.RepositoryService;
import edu.ucsb.cs156.jobs.entities.Job;
import edu.ucsb.cs156.jobs.services.JobService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import java.util.List;
import java.util.regex.Pattern;
import java.util.regex.PatternSyntaxException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * Assignments of a course, and the jobs that create their repositories. Creating or editing an
 * assignment saves it and starts the job that creates its individual or team repositories, and the
 * id of that job is kept as the assignment's last job id.
 */
@Tag(name = "Assignments")
@RequestMapping("/api/assignments")
@RestController
@Slf4j
public class AssignmentsController extends ApiController {

  /** The team regular expression that matches every team. */
  public static final String DEFAULT_TEAM_REGEX = ".*";

  @Autowired private AssignmentRepository assignmentRepository;

  @Autowired private CourseRepository courseRepository;

  @Autowired private RepositoryService repositoryService;

  @Autowired private GithubTeamService githubTeamService;

  @Autowired private JobService jobService;

  /**
   * Lists the assignments of a course, sorted by repository prefix.
   *
   * @param courseId the ID of the course
   * @return the assignments of the course
   */
  @Operation(summary = "List the assignments of a course")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @GetMapping("")
  public List<Assignment> getAssignments(@Parameter(name = "courseId") @RequestParam Long courseId)
      throws EntityNotFoundException {
    ensureCourseExists(courseId);
    return assignmentRepository.findByCourseIdOrderByRepoPrefixAsc(courseId);
  }

  /**
   * Creates an assignment and starts the job that creates its repositories.
   *
   * <p>For an INDIVIDUAL assignment, createReposFor says whom repositories are created for (default
   * STUDENTS_ONLY) and teamRegex must not be given. For a TEAM assignment, teamRegex is the regular
   * expression that team names must match (default {@value #DEFAULT_TEAM_REGEX}, every team) and
   * createReposFor must not be given.
   *
   * @param courseId the ID of the course the assignment is for
   * @param repoPrefix each repository created begins with this prefix
   * @param asnType the assignment type (individual vs team)
   * @param visibility the visibility of the repositories (public vs private)
   * @param permission the permission that students, or teams, have on the repositories
   * @param createReposFor INDIVIDUAL only: whom to create repositories for
   * @param teamRegex TEAM only: only teams whose names match get a repository
   * @param requireSignedCommit whether the repositories must require signed commits (default false)
   * @param restrictPrsToContributors TEAM only: whether pull requests are restricted to users with
   *     Write access (default false)
   * @return the created assignment, with the id of the job as its last job id, and that job
   */
  @Operation(summary = "Create an assignment and start creating its repositories")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @PostMapping("/post")
  public AssignmentWithJob postAssignment(
      @Parameter(name = "courseId") @RequestParam Long courseId,
      @Parameter(name = "repoPrefix") @RequestParam String repoPrefix,
      @Parameter(name = "asnType") @RequestParam AssignmentType asnType,
      @Parameter(name = "visibility") @RequestParam Visibility visibility,
      @Parameter(name = "permission") @RequestParam Permission permission,
      @Parameter(name = "createReposFor") @RequestParam(required = false)
          RepositoryCreationOption createReposFor,
      @Parameter(name = "teamRegex") @RequestParam(required = false) String teamRegex,
      @Parameter(name = "requireSignedCommit") @RequestParam(required = false)
          Boolean requireSignedCommit,
      @Parameter(name = "restrictPrsToContributors") @RequestParam(required = false)
          Boolean restrictPrsToContributors)
      throws EntityNotFoundException {
    Course course = ensureCourseExists(courseId);
    Assignment assignment = Assignment.builder().course(course).asnType(asnType).build();
    applyFields(
        assignment,
        repoPrefix,
        visibility,
        permission,
        createReposFor,
        teamRegex,
        requireSignedCommit,
        restrictPrsToContributors);
    requireLinkedOrganization(course);

    return launchAndSave(course, assignment);
  }

  /**
   * Updates an assignment and starts the job that creates its repositories. The assignment type
   * cannot be changed: to change an individual assignment to a team one, or the other way round,
   * delete the assignment and create a new one. The same rules as for creating apply to
   * createReposFor and teamRegex, according to the assignment's type.
   *
   * @param courseId the ID of the course the assignment belongs to
   * @param assignmentId the ID of the assignment
   * @param repoPrefix each repository created begins with this prefix
   * @param visibility the visibility of the repositories (public vs private)
   * @param permission the permission that students, or teams, have on the repositories
   * @param createReposFor INDIVIDUAL only: whom to create repositories for
   * @param teamRegex TEAM only: only teams whose names match get a repository
   * @param requireSignedCommit whether the repositories must require signed commits; if it is not
   *     given the assignment keeps its setting
   * @param restrictPrsToContributors TEAM only: whether pull requests are restricted to users with
   *     Write access; if it is not given the assignment keeps its setting
   * @return the updated assignment, with the id of the job as its last job id, and that job
   */
  @Operation(summary = "Update an assignment and start creating its repositories")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @PutMapping("/put")
  public AssignmentWithJob updateAssignment(
      @Parameter(name = "courseId") @RequestParam Long courseId,
      @Parameter(name = "assignmentId") @RequestParam Long assignmentId,
      @Parameter(name = "repoPrefix") @RequestParam String repoPrefix,
      @Parameter(name = "visibility") @RequestParam Visibility visibility,
      @Parameter(name = "permission") @RequestParam Permission permission,
      @Parameter(name = "createReposFor") @RequestParam(required = false)
          RepositoryCreationOption createReposFor,
      @Parameter(name = "teamRegex") @RequestParam(required = false) String teamRegex,
      @Parameter(name = "requireSignedCommit") @RequestParam(required = false)
          Boolean requireSignedCommit,
      @Parameter(name = "restrictPrsToContributors") @RequestParam(required = false)
          Boolean restrictPrsToContributors)
      throws EntityNotFoundException {
    Course course = ensureCourseExists(courseId);
    Assignment assignment = findAssignmentInCourse(courseId, assignmentId);
    applyFields(
        assignment,
        repoPrefix,
        visibility,
        permission,
        createReposFor,
        teamRegex,
        requireSignedCommit,
        restrictPrsToContributors);
    requireLinkedOrganization(course);

    return launchAndSave(course, assignment);
  }

  /**
   * Starts the job that creates the repositories of an existing assignment again, for example to
   * pick up students who have joined since the last run, and records it as the assignment's last
   * job.
   *
   * @param courseId the ID of the course the assignment belongs to
   * @param assignmentId the ID of the assignment
   * @return the assignment, with its new last job id, and the job that was started
   */
  @Operation(summary = "Start creating the repositories of an assignment")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @PostMapping("/launch")
  public AssignmentWithJob launchAssignmentJob(
      @Parameter(name = "courseId") @RequestParam Long courseId,
      @Parameter(name = "assignmentId") @RequestParam Long assignmentId)
      throws EntityNotFoundException {
    Course course = ensureCourseExists(courseId);
    Assignment assignment = findAssignmentInCourse(courseId, assignmentId);
    requireLinkedOrganization(course);

    return launchAndSave(course, assignment);
  }

  @Operation(summary = "Delete an assignment")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @DeleteMapping("/{id}")
  public Object deleteAssignment(
      @Parameter(name = "id") @PathVariable Long id,
      @Parameter(name = "courseId") @RequestParam Long courseId) {
    ensureCourseExists(courseId);
    Assignment assignment = findAssignmentInCourse(courseId, id);

    assignmentRepository.delete(assignment);

    return genericMessage(String.format("Assignment with id %s deleted", id));
  }

  private Course ensureCourseExists(Long courseId) {
    return courseRepository
        .findById(courseId)
        .orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
  }

  /** Finds an assignment, which must belong to the given course. */
  private Assignment findAssignmentInCourse(Long courseId, Long assignmentId) {
    return assignmentRepository
        .findById(assignmentId)
        .filter(a -> a.getCourse().getId().equals(courseId))
        .orElseThrow(() -> new EntityNotFoundException(Assignment.class, assignmentId));
  }

  /**
   * Starts the job that creates the assignment's repositories and saves the assignment with the id
   * of that job as its last job id.
   */
  private AssignmentWithJob launchAndSave(Course course, Assignment assignment) {
    Job job = launchJob(course, assignment);
    assignment.setLastJobId(job.getId());
    return new AssignmentWithJob(assignmentRepository.save(assignment), job);
  }

  private static void requireLinkedOrganization(Course course) {
    if (course.getOrgName() == null || course.getInstallationId() == null) {
      throw new NoLinkedOrganizationException(course.getCourseName());
    }
  }

  /**
   * Sets the editable fields of an assignment, checking the ones that depend on its type.
   *
   * @throws IllegalArgumentException if a field is blank, does not apply to the type of the
   *     assignment, or is not a valid regular expression
   */
  private static void applyFields(
      Assignment assignment,
      String repoPrefix,
      Visibility visibility,
      Permission permission,
      RepositoryCreationOption createReposFor,
      String teamRegex,
      Boolean requireSignedCommit,
      Boolean restrictPrsToContributors) {
    String normalizedPrefix = repoPrefix.strip();
    if (normalizedPrefix.isEmpty()) {
      throw new IllegalArgumentException("repoPrefix must not be blank");
    }
    boolean hasTeamRegex = teamRegex != null && !teamRegex.isBlank();

    if (assignment.getAsnType() == AssignmentType.TEAM) {
      if (createReposFor != null) {
        throw new IllegalArgumentException(
            "createReposFor is only allowed for INDIVIDUAL assignments");
      }
      String regex = hasTeamRegex ? teamRegex : DEFAULT_TEAM_REGEX;
      try {
        Pattern.compile(regex);
      } catch (PatternSyntaxException e) {
        throw new IllegalArgumentException("teamRegex is not a valid regular expression", e);
      }
      assignment.setCreateReposFor(null);
      assignment.setTeamRegex(regex);
    } else {
      if (hasTeamRegex) {
        throw new IllegalArgumentException("teamRegex is only allowed for TEAM assignments");
      }
      assignment.setCreateReposFor(
          createReposFor == null ? RepositoryCreationOption.STUDENTS_ONLY : createReposFor);
      assignment.setTeamRegex(null);
    }

    assignment.setRepoPrefix(normalizedPrefix);
    assignment.setVisibility(visibility);
    assignment.setPermission(permission);
    if (requireSignedCommit != null) {
      assignment.setRequireSignedCommit(requireSignedCommit);
    }
    if (restrictPrsToContributors != null) {
      assignment.setRestrictPrsToContributors(restrictPrsToContributors);
    }
  }

  /** Starts the job that creates the individual or team repositories of an assignment. */
  private Job launchJob(Course course, Assignment assignment) {
    boolean isPrivate = assignment.getVisibility() == Visibility.PRIVATE;
    RepositoryPermissions permissions =
        RepositoryPermissions.valueOf(assignment.getPermission().name());
    if (assignment.getAsnType() == AssignmentType.TEAM) {
      return jobService.runAsJob(
          CreateTeamRepositoriesJob.builder()
              .repositoryPrefix(assignment.getRepoPrefix())
              .isPrivate(isPrivate)
              .repositoryService(repositoryService)
              .githubTeamService(githubTeamService)
              .course(course)
              .permissions(permissions)
              .teamRegex(assignment.getTeamRegex())
              .requireSignedCommit(assignment.getRequireSignedCommit())
              .restrictPrsToContributors(assignment.getRestrictPrsToContributors())
              .build());
    }
    return jobService.runAsJob(
        CreateStudentOrStaffRepositoriesJob.builder()
            .repositoryPrefix(assignment.getRepoPrefix())
            .isPrivate(isPrivate)
            .repositoryService(repositoryService)
            .course(course)
            .permissions(permissions)
            .creationOption(assignment.getCreateReposFor())
            .requireSignedCommit(assignment.getRequireSignedCommit())
            .build());
  }
}