JobsController.java
package edu.ucsb.cs156.frontiers.controllers;
import edu.ucsb.cs156.frontiers.errors.EntityNotFoundException;
import edu.ucsb.cs156.frontiers.jobs.AddTeamMemberToGithubJob;
import edu.ucsb.cs156.frontiers.jobs.AddTeamToGithubJob;
import edu.ucsb.cs156.frontiers.jobs.DeleteTeamFromGithubJob;
import edu.ucsb.cs156.frontiers.jobs.DeleteTeamMemberFromGithubJob;
import edu.ucsb.cs156.frontiers.jobs.MembershipAuditJob;
import edu.ucsb.cs156.frontiers.jobs.PullTeamsFromGithubJob;
import edu.ucsb.cs156.frontiers.jobs.PushTeamsToGithubJob;
import edu.ucsb.cs156.frontiers.jobs.UpdateAllJob;
import edu.ucsb.cs156.frontiers.models.JobLogTail;
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.TeamMemberRepository;
import edu.ucsb.cs156.frontiers.repositories.TeamRepository;
import edu.ucsb.cs156.frontiers.services.GithubTeamService;
import edu.ucsb.cs156.frontiers.services.OrganizationMemberService;
import edu.ucsb.cs156.frontiers.services.UpdateUserService;
import edu.ucsb.cs156.jobs.entities.Job;
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 lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* App-level job endpoints: launching this app's concrete jobs, plus the course-scoped jobs listing
* and course-scoped full-log endpoint (which use this app's CourseSecurity rule). The generic admin
* endpoints (list all / paginated / logs / delete) come from the lib-jobs library's own controller.
*/
@Tag(name = "Jobs")
@RequestMapping("/api/jobs")
@RestController
@Slf4j
public class JobsController extends ApiController {
@Autowired private JobsRepository jobsRepository;
@Autowired private JobService jobService;
@Autowired private UpdateUserService updateUserService;
@Autowired private RosterStudentRepository rosterStudentRepository;
@Autowired private CourseRepository courseRepository;
@Autowired private OrganizationMemberService organizationMemberService;
@Autowired private CourseStaffRepository courseStaffRepository;
@Autowired private TeamRepository teamRepository;
@Autowired private TeamMemberRepository teamMemberRepository;
@Autowired private GithubTeamService githubTeamService;
@Operation(summary = "Launch UpdateAll job")
@PreAuthorize("hasRole('ROLE_ADMIN')")
@PostMapping("/launch/updateAll")
public Job launchUpdateAllJob() {
UpdateAllJob job = UpdateAllJob.builder().updateUserService(updateUserService).build();
return jobService.runAsJob(job);
}
@Operation(summary = "Launch Audit All Courses Job")
@PreAuthorize("hasRole('ROLE_ADMIN')")
@PostMapping("/launch/auditAllCourses")
public Job launchAuditAllCoursesJob() {
MembershipAuditJob job =
MembershipAuditJob.builder()
.rosterStudentRepository(rosterStudentRepository)
.courseRepository(courseRepository)
.organizationMemberService(organizationMemberService)
.courseStaffRepository(courseStaffRepository)
.build();
return jobService.runAsJob(job);
}
@Operation(summary = "Launch Push Teams to GitHub Job")
@PreAuthorize("hasRole('ROLE_ADMIN')")
@PostMapping("/launch/pushTeamsToGithub")
public Job launchPushTeamsToGithubJob(@Parameter(name = "courseId") @RequestParam Long courseId) {
PushTeamsToGithubJob job =
PushTeamsToGithubJob.builder()
.courseId(courseId)
.courseRepository(courseRepository)
.teamRepository(teamRepository)
.teamMemberRepository(teamMemberRepository)
.githubTeamService(githubTeamService)
.build();
return jobService.runAsJob(job);
}
@Operation(summary = "Launch Pull Teams from GitHub Job")
@PreAuthorize("hasRole('ROLE_ADMIN')")
@PostMapping("/launch/pullTeamsFromGithub")
public Job launchPullTeamsFromGithubJob(
@Parameter(name = "courseId") @RequestParam Long courseId) {
PullTeamsFromGithubJob job =
PullTeamsFromGithubJob.builder()
.courseId(courseId)
.courseRepository(courseRepository)
.teamRepository(teamRepository)
.teamMemberRepository(teamMemberRepository)
.githubTeamService(githubTeamService)
.build();
return jobService.runAsJob(job);
}
@Operation(summary = "Launch Delete Team Member From GitHub Job")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@PostMapping("/launch/deleteTeamMemberFromGithub")
public Job launchDeleteTeamMemberFromGithubJob(
@Parameter(name = "memberGithubLogin") @RequestParam String memberGithubLogin,
@Parameter(name = "githubTeamId") @RequestParam Integer githubTeamId,
@Parameter(name = "courseId") @RequestParam Long courseId) {
DeleteTeamMemberFromGithubJob job =
DeleteTeamMemberFromGithubJob.builder()
.memberGithubLogin(memberGithubLogin)
.githubTeamId(githubTeamId)
.course(courseRepository.findById(courseId).get())
.githubTeamService(githubTeamService)
.build();
return jobService.runAsJob(job);
}
@Operation(summary = "Launch Add Team Member To GitHub Job")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@PostMapping("/launch/addTeamMemberToGithub")
public Job launchAddTeamMemberToGithubJob(
@Parameter(name = "memberGithubLogin") @RequestParam String memberGithubLogin,
@Parameter(name = "githubTeamId") @RequestParam Integer githubTeamId,
@Parameter(name = "teamMemberId") @RequestParam Long teamMemberId,
@Parameter(name = "courseId") @RequestParam Long courseId) {
AddTeamMemberToGithubJob job =
AddTeamMemberToGithubJob.builder()
.memberGithubLogin(memberGithubLogin)
.githubTeamId(githubTeamId)
.teamMemberId(teamMemberId)
.course(courseRepository.findById(courseId).get())
.githubTeamService(githubTeamService)
.teamMemberRepository(teamMemberRepository)
.build();
return jobService.runAsJob(job);
}
@Operation(summary = "Launch Delete Team From GitHub Job")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@PostMapping("/launch/deleteTeamFromGithub")
public Job launchDeleteTeamFromGithubJob(
@Parameter(name = "githubTeamId") @RequestParam Integer githubTeamId,
@Parameter(name = "courseId") @RequestParam Long courseId) {
DeleteTeamFromGithubJob job =
DeleteTeamFromGithubJob.builder()
.githubTeamId(githubTeamId)
.course(courseRepository.findById(courseId).get())
.githubTeamService(githubTeamService)
.build();
return jobService.runAsJob(job);
}
@Operation(summary = "Launch Add Team To GitHub Job")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@PostMapping("/launch/addTeamToGithub")
public Job launchAddTeamToGithubJob(
@Parameter(name = "teamName") @RequestParam String teamName,
@Parameter(name = "courseId") @RequestParam Long courseId) {
AddTeamToGithubJob job =
AddTeamToGithubJob.builder()
.teamName(teamName)
.course(courseRepository.findById(courseId).get())
.teamRepository(teamRepository)
.githubTeamService(githubTeamService)
.build();
return jobService.runAsJob(job);
}
@Operation(summary = "List jobs by courseId")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@GetMapping("/course")
public Iterable<Job> jobsByCourse(@Parameter(name = "courseId") @RequestParam Long courseId) {
Iterable<Job> jobs = jobsRepository.findByScopeTypeAndScopeIdOrderByIdDesc("course", courseId);
/*
* Since lib-jobs v0.2.0, Job.log is @Transient (see job_logs) and is no
* longer populated automatically by JPA; callers that return Job entities
* directly must set it explicitly, same as the library's own controller
* does for /all and /paginated.
*/
jobs.forEach(job -> job.setLog(jobService.getJobLogPreview(job.getId())));
return jobs;
}
/**
* Returns the full log of one job that belongs to the given course.
*
* <p>Why this app-owned endpoint exists: the library's own {@code GET /api/jobs/logs/{id}}
* returns the full log but is restricted to {@code ROLE_ADMIN}. The per-course jobs tab is used
* by course instructors and staff who are not necessarily admins, and the course-scoped listing
* above only populates {@code Job.log} with a short tail preview ({@code
* JobService.getJobLogPreview}). This endpoint gives those users the same full log, guarded by
* the same course-permission rule as the listing.
*
* <p>A job that exists but is not scoped to the given course is deliberately reported as not
* found (404) rather than forbidden (403), so that job ids do not leak across courses.
*
* @param courseId the id of the course the job must belong to
* @param jobId the id of the job
* @return the full job log, oldest line first
*/
@Operation(summary = "Get the full log of one job belonging to a course")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@GetMapping("/course/logs")
public String jobLogsByCourse(
@Parameter(name = "courseId") @RequestParam Long courseId,
@Parameter(name = "jobId") @RequestParam Long jobId) {
findJobInCourse(courseId, jobId);
return jobService.getJobLogs(jobId);
}
/**
* Returns the log lines of one job that belong to the given course that were written after the
* line with id {@code afterId}, together with the job's status: one poll of a "tail -f" style
* view. The client keeps the id of the last line it has received and passes it as {@code afterId}
* on its next poll, and stops polling once the status is one of a job that has finished.
*
* <p>This is the course-scoped counterpart of the library's admin-only {@code GET
* /api/jobs/logs/{id}/tail}, for the same reason as {@link #jobLogsByCourse}. Like that endpoint
* it reports a job of another course as not found.
*
* <p>The status is read <em>before</em> the lines. If the job has already finished when its
* status is read, all of its lines have been written by the time they are read, so a client that
* stops polling on a finished status has not missed any. Reading them the other way round could
* miss the last lines of a job that finishes in between.
*
* @param courseId the id of the course the job must belong to
* @param jobId the id of the job
* @param afterId only lines with an id greater than this are returned; 0 for the whole log
* @return the status of the job and its new log lines, oldest first
*/
@Operation(summary = "Get the new log lines and the status of one job belonging to a course")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
@GetMapping("/course/logs/tail")
public JobLogTail jobLogTailByCourse(
@Parameter(name = "courseId") @RequestParam Long courseId,
@Parameter(name = "jobId") @RequestParam Long jobId,
@Parameter(name = "afterId", description = "only return lines with id greater than this")
@RequestParam(defaultValue = "0")
Long afterId) {
String status = findJobInCourse(courseId, jobId).getStatus();
return new JobLogTail(status, jobService.getJobLogTail(jobId, afterId));
}
/**
* Finds a job, which must be a course-scoped job of the given course.
*
* @throws EntityNotFoundException if there is no such job, or it belongs to something else
*/
private Job findJobInCourse(Long courseId, Long jobId) {
Job job =
jobsRepository
.findById(jobId)
.orElseThrow(() -> new EntityNotFoundException(Job.class, jobId));
if (!"course".equals(job.getScopeType()) || !courseId.equals(job.getScopeId())) {
throw new EntityNotFoundException(Job.class, jobId);
}
return job;
}
}