DokkuController.java
package edu.ucsb.cs156.frontiers.controllers;
import edu.ucsb.cs156.frontiers.entities.Course;
import edu.ucsb.cs156.frontiers.entities.CourseStaff;
import edu.ucsb.cs156.frontiers.entities.DokkuAccountTranslation;
import edu.ucsb.cs156.frontiers.entities.Team;
import edu.ucsb.cs156.frontiers.entities.TeamMember;
import edu.ucsb.cs156.frontiers.errors.EntityNotFoundException;
import edu.ucsb.cs156.frontiers.repositories.CourseRepository;
import edu.ucsb.cs156.frontiers.repositories.CourseStaffRepository;
import edu.ucsb.cs156.frontiers.repositories.DokkuAccountTranslationRepository;
import edu.ucsb.cs156.frontiers.repositories.TeamRepository;
import edu.ucsb.cs156.frontiers.utilities.CanonicalFormConverter;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.nio.charset.StandardCharsets;
import java.util.Collection;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.apache.commons.csv.CSVFormat;
import org.apache.commons.csv.CSVPrinter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
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.servlet.mvc.method.annotation.StreamingResponseBody;
/**
* Endpoints that produce files for setting up access to the UCSB Dokku servers (dokku-00 through
* dokku-18).
*/
@Tag(name = "Dokku")
@RequestMapping("/api/dokku")
@RestController
public class DokkuController extends ApiController {
/** The lowest numbered dokku instance, i.e. dokku-00. */
public static final int LOWEST_DOKKU_NUMBER = 0;
/** The highest numbered dokku instance, i.e. dokku-18. */
public static final int HIGHEST_DOKKU_NUMBER = 18;
/**
* Matches team names of the form {@code xxx-yy}: anything, a literal hyphen, then exactly two
* digits at the end. The two digits are captured as group 1 and are the dokku number.
*/
static final Pattern TEAM_NAME_PATTERN = Pattern.compile("^.*-(\\d{2})$");
/**
* Every dokku instance name, keyed by its two digit suffix and ordered from {@link
* #LOWEST_DOKKU_NUMBER} to {@link #HIGHEST_DOKKU_NUMBER}, e.g. {@code "07" -> "dokku-07"}. This
* is the single place the range of dokku numbers is expanded.
*/
static final Map<String, String> DOKKU_NAME_BY_SUFFIX = dokkuNamesBySuffix();
private static Map<String, String> dokkuNamesBySuffix() {
Map<String, String> names = new LinkedHashMap<>();
for (int n = LOWEST_DOKKU_NUMBER; n <= HIGHEST_DOKKU_NUMBER; n++) {
String suffix = String.format("%02d", n);
names.put(suffix, "dokku-" + suffix);
}
return names;
}
@Autowired private CourseRepository courseRepository;
@Autowired private CourseStaffRepository courseStaffRepository;
@Autowired private TeamRepository teamRepository;
@Autowired private DokkuAccountTranslationRepository dokkuAccountTranslationRepository;
/**
* Returns every dokku instance name in order, {@code dokku-00} through {@code dokku-18}.
*
* @return the dokku instance names
*/
public static Collection<String> allDokkuNames() {
return DOKKU_NAME_BY_SUFFIX.values();
}
/**
* Extracts the dokku username from an email address: everything before the first {@code @}. An
* email with no {@code @} is returned unchanged.
*
* @param email the email address
* @return the username
*/
public static String usernameFromEmail(String email) {
int at = email.indexOf('@');
return at < 0 ? email : email.substring(0, at);
}
/**
* Returns the dokku username for an email: the translated username if there is a {@link
* DokkuAccountTranslation} for the email (compared in canonical form), otherwise the part of the
* email before the {@code @}.
*
* @param email the email address
* @param translations map from canonical email to dokku username
* @return the dokku username
*/
public static String usernameFor(String email, Map<String, String> translations) {
String translated = translations.get(CanonicalFormConverter.convertToValidEmail(email));
return translated != null ? translated : usernameFromEmail(email);
}
/**
* Returns the dokku instance named by a team, if the team name has the form {@code xxx-yy} and
* {@code yy} is between {@link #LOWEST_DOKKU_NUMBER} and {@link #HIGHEST_DOKKU_NUMBER} inclusive.
*
* @param teamName the team name, e.g. {@code "s26-07"}
* @return the dokku instance name, e.g. {@code "dokku-07"}, or empty if the team does not
* correspond to a dokku instance
*/
public static Optional<String> dokkuNameForTeam(String teamName) {
if (teamName == null) {
return Optional.empty();
}
Matcher matcher = TEAM_NAME_PATTERN.matcher(teamName);
if (!matcher.matches()) {
return Optional.empty();
}
return Optional.ofNullable(DOKKU_NAME_BY_SUFFIX.get(matcher.group(1)));
}
@Operation(
summary = "Download dokku_users_list.csv for a course",
description =
"Returns a CSV file with no header line and one `username,dokku-nn` line per grant of"
+ " access. Every staff member of the course is granted access to every dokku"
+ " instance from dokku-"
+ LOWEST_DOKKU_NUMBER
+ " through dokku-"
+ HIGHEST_DOKKU_NUMBER
+ ". Each member of a team whose name ends in `-nn` (nn between "
+ LOWEST_DOKKU_NUMBER
+ " and "
+ HIGHEST_DOKKU_NUMBER
+ ") is granted access to dokku-nn; other teams are ignored. Usernames are the part"
+ " of the email before the @, unless the email has a dokku account translation, in"
+ " which case the translated username is used.",
responses = {
@ApiResponse(
responseCode = "200",
description = "CSV file",
content =
@Content(
mediaType = "text/csv",
schema = @Schema(type = "string", format = "binary"))),
@ApiResponse(responseCode = "404", description = "Course not found"),
@ApiResponse(responseCode = "500", description = "Internal Server Error")
})
@GetMapping(value = "/dokku_users_list", produces = "text/csv")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
public ResponseEntity<StreamingResponseBody> dokkuUsersList(
@Parameter(name = "courseId", description = "course id", example = "1") @RequestParam
Long courseId)
throws EntityNotFoundException {
Course course =
courseRepository
.findById(courseId)
.orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
StreamingResponseBody stream =
(outputStream) -> {
try (Writer writer = new OutputStreamWriter(outputStream, StandardCharsets.UTF_8);
CSVPrinter csvPrinter = new CSVPrinter(writer, CSVFormat.DEFAULT)) {
writeHeaderLines(writer, course.getDokkuUsersListHeader());
Map<String, String> translations = translationsByEmail();
writeStaffLines(
csvPrinter, courseStaffRepository.findByCourseId(courseId), translations);
writeTeamLines(
csvPrinter, teamRepository.findByCourseIdOrderByNameAsc(courseId), translations);
}
};
return ResponseEntity.ok()
.contentType(MediaType.parseMediaType("text/csv; charset=UTF-8"))
.header(HttpHeaders.CONTENT_DISPOSITION, "attachment;filename=dokku_users_list.csv")
.header(HttpHeaders.CONTENT_TYPE, "text/csv; charset=UTF-8")
.header(HttpHeaders.ACCESS_CONTROL_EXPOSE_HEADERS, HttpHeaders.CONTENT_DISPOSITION)
.body(stream);
}
@Operation(
summary = "Get the extra lines placed at the start of dokku_users_list.csv for a course",
description =
"Returns the course's dokkuUsersListHeader as plain text, or an empty body if none is"
+ " set.")
@GetMapping(value = "/users_list_header", produces = "text/plain")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
public String getUsersListHeader(
@Parameter(name = "courseId", description = "course id", example = "1") @RequestParam
Long courseId)
throws EntityNotFoundException {
Course course =
courseRepository
.findById(courseId)
.orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
return course.getDokkuUsersListHeader() == null ? "" : course.getDokkuUsersListHeader();
}
@Operation(
summary = "Set the extra lines placed at the start of dokku_users_list.csv for a course",
description =
"The request body (plain text, line breaks preserved) replaces the course's"
+ " dokkuUsersListHeader. A blank body clears it. Returns the saved text.")
@PutMapping(value = "/users_list_header", consumes = "text/plain", produces = "text/plain")
@PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
public String setUsersListHeader(
@Parameter(name = "courseId", description = "course id", example = "1") @RequestParam
Long courseId,
@Parameter(name = "header") @RequestBody(required = false) String header)
throws EntityNotFoundException {
Course course =
courseRepository
.findById(courseId)
.orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
String normalized = header == null || header.isBlank() ? null : header;
course.setDokkuUsersListHeader(normalized);
courseRepository.save(course);
return normalized == null ? "" : normalized;
}
/**
* Writes the course's dokkuUsersListHeader before any generated lines: one line per non-blank
* line of the header, stripped, with line endings normalized to the CSV record separator. The
* lines are written verbatim (not as quoted CSV fields), since each is already a
* username,dokku-nn entry. Nothing is written when the header is null.
*/
private static void writeHeaderLines(Writer writer, String header) throws IOException {
if (header == null) {
return;
}
for (String line : header.split("\\R")) {
String trimmed = line.strip();
if (!trimmed.isEmpty()) {
writer.write(trimmed);
writer.write(CSVFormat.DEFAULT.getRecordSeparator());
}
}
}
/** Loads every {@link DokkuAccountTranslation} into a map from canonical email to username. */
private Map<String, String> translationsByEmail() {
Map<String, String> translations = new HashMap<>();
for (DokkuAccountTranslation translation : dokkuAccountTranslationRepository.findAll()) {
translations.put(
CanonicalFormConverter.convertToValidEmail(translation.getEmail()),
translation.getUsername());
}
return translations;
}
/**
* Writes one line per staff member per dokku instance: each staff member gets access to every
* instance from {@link #LOWEST_DOKKU_NUMBER} through {@link #HIGHEST_DOKKU_NUMBER}.
*/
private static void writeStaffLines(
CSVPrinter csvPrinter, Iterable<CourseStaff> staff, Map<String, String> translations)
throws IOException {
for (CourseStaff member : staff) {
String username = usernameFor(member.getEmail(), translations);
for (String dokku : allDokkuNames()) {
csvPrinter.printRecord(username, dokku);
}
}
}
/**
* Writes one line per member of each team whose name maps to a dokku instance (see {@link
* #dokkuNameForTeam(String)}); teams that do not map to a dokku instance are skipped.
*/
private static void writeTeamLines(
CSVPrinter csvPrinter, Iterable<Team> teams, Map<String, String> translations)
throws IOException {
for (Team team : teams) {
Optional<String> dokku = dokkuNameForTeam(team.getName());
if (dokku.isEmpty()) {
continue;
}
List<TeamMember> members = team.getTeamMembers();
if (members == null) {
continue;
}
for (TeamMember member : members) {
csvPrinter.printRecord(
usernameFor(member.getRosterStudent().getEmail(), translations), dokku.get());
}
}
}
}