CoursesController.java

package edu.ucsb.cs.scaffold.controller;

import com.fasterxml.jackson.databind.JsonNode;

import com.fasterxml.jackson.databind.ObjectMapper;

import edu.ucsb.cs.scaffold.entity.Course;

import edu.ucsb.cs.scaffold.entity.CourseStaff;

import edu.ucsb.cs.scaffold.entity.PatCredential;

import edu.ucsb.cs.scaffold.entity.PlInstance;

import edu.ucsb.cs.scaffold.entity.PlRepo;

import edu.ucsb.cs.scaffold.entity.RosterStudent;

import edu.ucsb.cs.scaffold.entity.User;

import edu.ucsb.cs.scaffold.enums.PatPlatform;

import edu.ucsb.cs.scaffold.enums.School;

import edu.ucsb.cs.scaffold.errors.EntityNotFoundException;

import edu.ucsb.cs.scaffold.errors.ForbiddenException;

import edu.ucsb.cs.scaffold.jobs.SyncCourseWithPlRepoJobFactory;

import edu.ucsb.cs.scaffold.model.CurrentUser;

import edu.ucsb.cs.scaffold.repository.AdminRepository;

import edu.ucsb.cs.scaffold.repository.CourseRepository;

import edu.ucsb.cs.scaffold.repository.CourseStaffRepository;

import edu.ucsb.cs.scaffold.repository.InstructorRepository;

import edu.ucsb.cs.scaffold.repository.PatCredentialRepository;

import edu.ucsb.cs.scaffold.repository.PlInstanceRepository;

import edu.ucsb.cs.scaffold.repository.PlRepoRepository;

import edu.ucsb.cs.scaffold.repository.RosterStudentRepository;

import edu.ucsb.cs.scaffold.repository.UserRepository;

import edu.ucsb.cs.scaffold.services.GithubService;

import edu.ucsb.cs.scaffold.services.PatEncryptionService;

import edu.ucsb.cs.scaffold.services.PrairieLearnService;

import edu.ucsb.cs156.jobs.repositories.JobsRepository;

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.security.NoSuchAlgorithmException;

import java.security.spec.InvalidKeySpecException;

import java.util.ArrayList;

import java.util.HashSet;

import java.util.List;

import java.util.Map;

import java.util.Objects;

import java.util.Set;

import java.util.stream.Collectors;

import java.util.stream.StreamSupport;

import lombok.extern.slf4j.Slf4j;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.security.access.prepost.PreAuthorize;

import org.springframework.transaction.annotation.Transactional;

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;

import org.springframework.web.client.HttpClientErrorException;

@Tag(name = "Course")

@RequestMapping("/api/courses")

@RestController

  @Autowired private CourseRepository courseRepository;

  @Autowired private UserRepository userRepository;

  @Autowired private RosterStudentRepository rosterStudentRepository;

  @Autowired private CourseStaffRepository courseStaffRepository;

  @Autowired private InstructorRepository instructorRepository;

  @Autowired private AdminRepository adminRepository;

  @Autowired private JobsRepository jobsRepository;

  @Autowired private PatCredentialRepository patCredentialRepository;

  @Autowired private PatEncryptionService patEncryptionService;

  @Autowired private PlRepoRepository plRepoRepository;

  @Autowired private GithubService githubService;

  @Autowired private PlInstanceRepository plInstanceRepository;

  @Autowired private PrairieLearnService prairieLearnService;

  @Autowired private SyncCourseWithPlRepoJobFactory syncCourseWithPlRepoJobFactory;

  @Autowired private JobService jobService;

  /**

   * This method creates a new Course.

   *

   * @param courseName the name of the course

   * @param term the term of the course

   * @param school the school of the course

   * @param canvasApiToken the Canvas API token (optional)

   * @param canvasCourseId the Canvas course ID (optional)

   */

  @Operation(summary = "Create a new course")

  @PreAuthorize("hasRole('ROLE_ADMIN') || hasRole('ROLE_INSTRUCTOR')")

  @PostMapping("/post")

  public InstructorCourseView postCourse(

      @Parameter(name = "courseName") @RequestParam String courseName,

      @Parameter(name = "term") @RequestParam String term,

      @Parameter(name = "school") @RequestParam School school,

      @Parameter(name = "canvasApiToken") @RequestParam(required = false) String canvasApiToken,

      @Parameter(name = "canvasCourseId") @RequestParam(required = false) String canvasCourseId) {

    // get current date right now and set status to pending

    Course course =

  }

  /** Projection of Course entity with fields that are relevant for instructors and admins */

      Long id,

      String courseName,

      String term,

      School school,

      String instructorEmail,

      int numStudents,

      int numStaff,

      Long plRepoId,

      Long plInstanceId,

      // Human-readable details of the PL associations; resolved only by the

      // single-course endpoints (getCourseById and the two update endpoints),

      // null in course lists.

      String plRepoName,

      String plInstanceShortName,

      Long plInstanceNumericId) {

    // Creates view from Course entity

    public InstructorCourseView(Course c) {

          null,

          null,

          null);

  }

  /**

   * Builds an InstructorCourseView with the PL association details (repo name, instance short name,

   * instance numeric id) resolved from their tables — used by the single-course endpoints so the

   * frontend can show what is currently associated. List endpoints use the plain constructor and

   * leave these null.

   */

  private InstructorCourseView viewWithPlDetails(Course c) {

    String plRepoName =

    PlInstance plInstance =

        plRepoName,

  }

  /**

   * This method returns a list of courses.

   *

   * @return a list of all courses for an instructor.

   */

  @Operation(summary = "List all courses for an instructor")

  @PreAuthorize("hasRole('ROLE_INSTRUCTOR')")

  @GetMapping("/list/instructors")

  public Iterable<InstructorCourseView> allForInstructors() {

  }

  /**

   * This method returns a list of courses.

   *

   * @return a list of all courses for an admin.

   */

  @Operation(summary = "List all courses for an admin")

  @PreAuthorize("hasRole('ROLE_ADMIN')")

  @GetMapping("/list/admins")

  public Iterable<InstructorCourseView> allForAdmins() {

  }

  /**

   * This method returns single course by its id

   *

   * @return a course

   */

  @Operation(summary = "Get course by id")

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #id)")

  @GetMapping("/{id}")

  public InstructorCourseView getCourseById(@Parameter(name = "id") @PathVariable Long id) {

        courseRepository

  }

  /**

   * This method returns the Canvas course ID and partially obscured Canvas token for a course by

   * its id. If the token is less than or equal to 3 characters long, it is returned in full.

   * Otherwise, all but the last three characters are replaced with asterisks. This is okay because

   * such short tokens are not generated by Canvas.

   *

   * @param courseId the id of the course

   * @return a map with courseId, canvasCourseId, and obscured canvasApiToken

   */

  @Operation(summary = "Get course Canvas course ID and Canvas token (partially obscured)")

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")

  @GetMapping("getCanvasInfo")

  public Map<String, String> getCourseCanvasInfo(

      @Parameter(name = "courseId") @RequestParam Long courseId) {

        courseRepository

      } else {

      }

    }

  }

      Long id, String courseName, String term, String school, Long rosterStudentId) {}

  /**

   * This method returns a list of courses that the current user is enrolled.

   *

   * @return a list of courses in the DTO form along with the student status in the organization.

   */

  @Operation(summary = "List all courses for the current student, including their org status")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/list/students")

  public List<RosterStudentCoursesDTO> listCoursesForCurrentUser() {

            rs -> {

                  new RosterStudentCoursesDTO(

            })

  }

      Long id, String courseName, String term, School school, Long staffId) {}

  }

  }

  /**

   * student see what courses they appear as staff in

   *

   * @param studentId the id of the student making request

   * @return a list of all courses student is staff in

   */

  @Operation(summary = "Student see what courses they appear as staff in")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/list/staff")

  public List<StaffCoursesDTO> staffCourses() {

            s -> {

                  new StaffCoursesDTO(

            })

  }

  /** DTO representing a course along with the ways in which the current user has access to it. */

      Long id,

      String courseName,

      String term,

      School school,

      String instructorEmail,

      boolean studentAccess,

      boolean staffAccess,

      boolean instructorAccess,

      boolean adminAccess) {}

  /**

   * This method returns a unified list of courses that the current user has access to, whether as a

   * student, staff member, instructor, or admin.

   *

   * @return a list of courses along with the access flags for the current user.

   */

  @Operation(summary = "List all courses the current user has access to")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/list")

  public List<CourseListDTO> listCoursesForCurrentUserUnified() {

    List<Course> courses;

    } else {

    }

            c ->

                    isAdmin))

  }

  /**

   * This method returns the unified access info for a single course, if the current user has access

   * to it. If the user does not have access, or the course does not exist, a 404 is returned.

   *

   * @param courseId the id of the course

   * @return the course along with the access flags for the current user.

   */

  @Operation(summary = "Get unified course access info for a single course")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/list/{courseId}")

  public CourseListDTO getCourseAccessInfo(

      @Parameter(name = "courseId") @PathVariable Long courseId) {

        courseRepository

    }

        studentAccess,

        staffAccess,

        instructorAccess,

        isAdmin);

  }

  @Operation(summary = "Update instructor email for a course (admin only)")

  @PreAuthorize("hasRole('ROLE_ADMIN')")

  @PutMapping("/updateInstructor")

  public InstructorCourseView updateInstructorEmail(

      @Parameter(name = "courseId") @RequestParam Long courseId,

      @Parameter(name = "instructorEmail") @RequestParam String instructorEmail) {

        courseRepository

    // Validate that the email exists in either instructor or admin table

    }

  }

  @Operation(summary = "Get course emails")

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")

  @GetMapping("/emails")

  public String getCourseEmails(

      @Parameter(name = "courseId") @RequestParam Long courseId,

      @Parameter(name = "type") @RequestParam(defaultValue = "STUDENTS") EmailTypes type,

      @Parameter(name = "format") @RequestParam(defaultValue = "ONE_PER_LINE")

          EmailFormats format) {

    }

  }

  @Operation(summary = "Delete a course")

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")

  @DeleteMapping("")

  @Transactional

  public Object deleteCourse(@RequestParam Long courseId)

      throws NoSuchAlgorithmException, InvalidKeySpecException {

        courseRepository

    // Check if course has roster students or staff

    }

  }

  /**

   * This method updates an existing course.

   *

   * @param courseId the id of the course to update

   * @param courseName the new name of the course

   * @param term the new term of the course

   * @param school the new school of the course

   * @return the updated course

   */

  @Operation(summary = "Update an existing course")

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")

  @PutMapping("")

  public InstructorCourseView updateCourse(

      @Parameter(name = "courseId") @RequestParam Long courseId,

      @Parameter(name = "courseName") @RequestParam String courseName,

      @Parameter(name = "term") @RequestParam String term,

      @Parameter(name = "school") @RequestParam School school) {

        courseRepository

  }

  /**

   * This method updates an existing course.

   *

   * @param courseId the id of the course to update

   * @param courseName the new name of the course

   * @param term the new term of the course

   * @param school the new school of the course

   * @param canvasApiToken the new Canvas API token for the course

   * @param canvasCourseId the new Canvas course ID

   * @return the updated course

   */

  @Operation(summary = "Update an existing course with Canvas token and course ID")

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")

  @PutMapping("/updateCourseCanvasToken")

  public InstructorCourseView updateCourseWithCanvasToken(

      @Parameter(name = "courseId") @RequestParam Long courseId,

      @Parameter(name = "canvasApiToken") @RequestParam(required = false) String canvasApiToken,

      @Parameter(name = "canvasCourseId") @RequestParam(required = false) String canvasCourseId) {

        courseRepository

    }

    }

  }

  /**

   * Associates a GitHub repo (PlRepo) with a course, after verifying that the current user's stored

   * GitHub PAT has read/write access to the repo. The check is a single GET /repos/{owner}/{repo}

   * call: a successful response proves read access and its permissions block reports push (write)

   * access, so nothing is written to the repo.

   *

   * @param courseId the id of the course

   * @param repoName the repo in owner/repo form (i.e. the part after https://github.com/)

   * @return the updated course

   */

  @Operation(summary = "Associate a GitHub repo (PlRepo) with a course")

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")

  @PutMapping("/updateGithubRepo")

  public InstructorCourseView updateGithubRepo(

      @Parameter(name = "courseId") @RequestParam Long courseId,

      @Parameter(name = "repoName", description = "GitHub repo in owner/repo form") @RequestParam

          String repoName) {

        courseRepository

        patCredentialRepository

    boolean canWrite;

    try {

    }

        plRepoRepository

  }

  /**

   * Associates a PrairieLearn course instance (PlInstance) with a course. The numeric instance id

   * is verified in two steps: it is fetched from the PrairieLearn API using the caller's

   * PrairieLearn PAT, and the course's GitHub repo must contain a matching

   * courseInstances/{shortName}/infoCourseInstance.json whose longName agrees. Only the

   * PrairieLearn API can supply the numeric id, and only the repo check proves the instance belongs

   * to this course's repo.

   *

   * @param courseId the id of the course

   * @param instanceId PrairieLearn's numeric course instance id

   * @return the updated course

   */

  @Operation(summary = "Associate a PrairieLearn course instance (PlInstance) with a course")

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")

  @PutMapping("/updatePLInstance")

  public InstructorCourseView updatePLInstance(

      @Parameter(name = "courseId") @RequestParam Long courseId,

      @Parameter(name = "instanceId", description = "numeric PrairieLearn course instance id")

          @RequestParam

          Long instanceId) {

        courseRepository

        patCredentialRepository

        patCredentialRepository

    }

        plRepoRepository

    PrairieLearnService.CourseInstanceInfo info;

    try {

    }

    }

        plInstanceRepository

                () ->

    // A successful association immediately kicks off a sync of the course's questions and

    // assessments (issue #69), so the instructor doesn't have to launch it by hand.

  }

  /**

   * True when the course's repo has courseInstances/{shortName}/infoCourseInstance.json and its

   * longName matches the one PrairieLearn reported for the instance.

   */

  private boolean repoConfirmsInstance(

      PlRepo plRepo, PrairieLearnService.CourseInstanceInfo info, String githubToken) {

    String infoJson;

    try {

              githubToken);

    try {

    }

  }

}

Mutations