CanvasService.java

package edu.ucsb.cs156.frontiers.services;

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import edu.ucsb.cs156.frontiers.entities.Course;
import edu.ucsb.cs156.frontiers.entities.RosterStudent;
import edu.ucsb.cs156.frontiers.models.CanvasGroup;
import edu.ucsb.cs156.frontiers.models.CanvasGroupDetail;
import edu.ucsb.cs156.frontiers.models.CanvasGroupSet;
import edu.ucsb.cs156.frontiers.models.CanvasGroupSetDetail;
import edu.ucsb.cs156.frontiers.models.CanvasStudent;
import edu.ucsb.cs156.frontiers.utilities.CanonicalFormConverter;
import edu.ucsb.cs156.frontiers.validators.HasLinkedCanvasCourse;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import org.springframework.graphql.client.ClientGraphQlResponse;
import org.springframework.graphql.client.GraphQlClient;
import org.springframework.graphql.client.HttpSyncGraphQlClient;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Service;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.client.RestClient;

/**
 * Service for interacting with the Canvas API.
 *
 * <p>Note that the Canvas API uses a GraphQL endpoint, which allows for more flexible queries
 * compared to traditional REST APIs.
 *
 * <p>For more information on the Canvas API, visit the official documentation at <a
 * href="https://canvas.instructure.com/doc/api/">...</a>.
 *
 * <p>You can typically interact with Canvas API GraphQL endpoints interactively by appending
 * /graphiql to the URL of the Canvas instance.
 *
 * <p>For example, for UCSB Canvas, use: <a href="https://ucsb.instructure.com/graphiql">...</a>
 *
 * <p>Every Canvas GraphQL connection is paginated: without a {@code first} argument Canvas returns
 * only the first page (20 items by default), and it never returns more than {@link #PAGE_SIZE} per
 * request. Every connection read here therefore asks for {@link #PAGE_SIZE} items and follows
 * {@code pageInfo.endCursor} until {@code hasNextPage} is false.
 */
@Service
@Validated
public class CanvasService {

  /** The largest page Canvas allows (its default_max_page_size). */
  static final int PAGE_SIZE = 100;

  private HttpSyncGraphQlClient graphQlClient;
  private RestClient restClient;
  private ObjectMapper mapper;
  private CanvasApiTokenSecurityService canvasApiTokenSecurityService;

  public CanvasService(
      ObjectMapper mapper,
      RestClient.Builder builder,
      CanvasApiTokenSecurityService canvasApiTokenSecurityService) {
    this.graphQlClient = HttpSyncGraphQlClient.builder(builder.build()).build();
    this.restClient = builder.build();
    this.mapper = mapper;
    this.mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
    this.canvasApiTokenSecurityService = canvasApiTokenSecurityService;
  }

  public List<CanvasGroupSet> getCanvasGroupSets(@HasLinkedCanvasCourse Course course) {
    // language=GraphQL
    String query =
        """
        query GetGroupSets($courseId: ID!) {
          course(id: $courseId) {
            groupSets {
              _id
              name
              id
            }
          }
        }
        """;

    HttpSyncGraphQlClient authedClient = authedClient(course);

    List<CanvasGroupSet> groupSets =
        authedClient
            .document(query)
            .variable("courseId", course.getCanvasCourseId())
            .retrieveSync("course.groupSets")
            .toEntityList(CanvasGroupSet.class);
    return groupSets;
  }

  /**
   * Fetches the roster of students from Canvas for the given course, following pagination so that
   * every enrolled student is returned.
   *
   * @param course the Course entity containing canvasApiToken and canvasCourseId
   * @return list of RosterStudent objects from Canvas
   */
  public List<RosterStudent> getCanvasRoster(@HasLinkedCanvasCourse Course course) {
    String nodeFields =
        """
            firstName
            lastName
            sisId
            email
            integrationId
            enrollments(courseId: $courseId) {
              section {
                name
              }
            }
            """;

    List<CanvasStudent> students =
        studentEdges(course, nodeFields).stream()
            .map(edge -> toCanvasStudent(edge.get("node")))
            .toList();

    return students.stream()
        .map(
            student ->
                RosterStudent.builder()
                    .firstName(student.getFirstName())
                    .lastName(student.getLastName())
                    .studentId(student.getStudentId())
                    .email(student.getEmail())
                    .section(student.getSection() != null ? student.getSection() : "")
                    .build())
        .toList();
  }

  private CanvasStudent toCanvasStudent(JsonNode userNode) {
    CanvasStudent canvasStudent = mapper.convertValue(userNode, CanvasStudent.class);
    JsonNode enrollments = userNode.path("enrollments");
    if (enrollments.isArray() && !enrollments.isEmpty()) {
      JsonNode sectionName = enrollments.get(0).path("section").path("name");
      if (sectionName.isTextual()) {
        String name = sectionName.asText();
        canvasStudent.setSection(name.substring(0, Math.min(5, name.length())));
      }
    }
    return canvasStudent;
  }

  /**
   * Fetches the groups in a Canvas group set with their members' emails, as used by the pull-teams
   * job. This is a view of {@link #getCanvasGroupSetDetail}.
   *
   * @param course the course, which must be linked to Canvas
   * @param groupSetId the group set's GraphQL relay id or numeric Canvas id
   * @return the groups, each with its members' canonical emails
   */
  public List<CanvasGroup> getCanvasGroups(
      @HasLinkedCanvasCourse Course course, String groupSetId) {
    List<CanvasGroup> groups = new ArrayList<>();
    for (CanvasGroupDetail group : getCanvasGroupSetDetail(course, groupSetId).getGroups()) {
      groups.add(
          CanvasGroup.builder()
              .name(group.getName())
              .id(group.getId())
              .members(new ArrayList<>(group.getMemberUserIdsByEmail().keySet()))
              .build());
    }
    return groups;
  }

  /**
   * Fetches a Canvas group set with everything the push-to-Canvas job needs: the numeric ids of the
   * group set and its groups, and each group's members as canonical email to numeric Canvas user
   * id. Group membership is paginated, so groups with more than {@link #PAGE_SIZE} members are
   * completed with follow-up queries.
   *
   * @param course the course, which must be linked to Canvas
   * @param groupSetId the group set's GraphQL relay id (as returned by getCanvasGroupSets) or its
   *     numeric Canvas id (as shown in Canvas URLs)
   * @return the group set detail
   */
  public CanvasGroupSetDetail getCanvasGroupSetDetail(
      @HasLinkedCanvasCourse Course course, String groupSetId) {
    String query =
        "query GetGroupSetDetail($groupId: ID!, $first: Int!) { groupSet: "
            + groupSetSelector(groupSetId)
            + """
                 {
                ... on GroupSet {
                  _id
                  name
                  groups {
                    _id
                    name
                    membersConnection(first: $first) {
                      edges {
                        node {
                          user {
                            _id
                            email
                          }
                        }
                      }
                      pageInfo {
                        hasNextPage
                        endCursor
                      }
                    }
                  }
                }
              }
            }
            """;

    HttpSyncGraphQlClient client = authedClient(course);
    JsonNode node =
        client
            .document(query)
            .variable("groupId", groupSetId)
            .variable("first", PAGE_SIZE)
            .retrieveSync("groupSet")
            .toEntity(JsonNode.class);

    List<CanvasGroupDetail> groups = new ArrayList<>();
    for (JsonNode group : node.path("groups")) {
      Integer groupId = group.path("_id").asInt();
      List<JsonNode> edges = new ArrayList<>();
      group.path("membersConnection").path("edges").forEach(edges::add);
      JsonNode pageInfo = group.path("membersConnection").path("pageInfo");
      if (pageInfo.path("hasNextPage").asBoolean()) {
        edges.addAll(
            remainingGroupMemberEdges(client, groupId, pageInfo.path("endCursor").asText()));
      }
      Map<String, Integer> members = new LinkedHashMap<>();
      for (JsonNode edge : edges) {
        JsonNode user = edge.path("node").path("user");
        members.put(
            CanonicalFormConverter.convertToValidEmail(user.path("email").asText()),
            user.path("_id").asInt());
      }
      groups.add(
          CanvasGroupDetail.builder()
              .id(groupId)
              .name(group.path("name").asText())
              .memberUserIdsByEmail(members)
              .build());
    }
    return CanvasGroupSetDetail.builder()
        .id(node.path("_id").asInt())
        .name(node.path("name").asText())
        .groups(groups)
        .build();
  }

  /**
   * Fetches the numeric Canvas user id of every student enrolled in the Canvas course, keyed by
   * canonical email, following pagination so that every enrolled student is included.
   *
   * @param course the course, which must be linked to Canvas
   * @return map from canonical email to Canvas user id
   */
  public Map<String, Integer> getCanvasUserIdsByEmail(@HasLinkedCanvasCourse Course course) {
    Map<String, Integer> userIds = new LinkedHashMap<>();
    for (JsonNode edge : studentEdges(course, "_id\nemail\n")) {
      JsonNode user = edge.path("node");
      userIds.put(
          CanonicalFormConverter.convertToValidEmail(user.path("email").asText()),
          user.path("_id").asInt());
    }
    return userIds;
  }

  /**
   * Creates a group in a Canvas group set.
   *
   * @param course the course, which must be linked to Canvas
   * @param groupSetId the numeric Canvas id of the group set
   * @param name the name of the new group
   * @return the numeric Canvas id of the new group
   * @throws RuntimeException if Canvas reports a validation error
   */
  public Integer createCanvasGroup(
      @HasLinkedCanvasCourse Course course, Integer groupSetId, String name) {
    // language=GraphQL
    String mutation =
        """
            mutation CreateGroup($groupSetId: ID!, $name: String!) {
              createGroupInSet(input: {groupSetId: $groupSetId, name: $name}) {
                group {
                  _id
                }
                errors {
                  message
                }
              }
            }
            """;

    ClientGraphQlResponse response =
        authedClient(course)
            .document(mutation)
            .variable("groupSetId", groupSetId.toString())
            .variable("name", name)
            .executeSync();
    JsonNode payload = response.field("createGroupInSet").toEntity(JsonNode.class);
    JsonNode errors = payload.path("errors");
    if (errors.isArray() && !errors.isEmpty()) {
      throw new RuntimeException(
          "Canvas refused to create group " + name + ": " + errors.get(0).path("message").asText());
    }
    return payload.path("group").path("_id").asInt();
  }

  /**
   * Deletes a Canvas group.
   *
   * @param course the course, which must be linked to Canvas
   * @param groupId the numeric Canvas id of the group
   */
  public void deleteCanvasGroup(@HasLinkedCanvasCourse Course course, Integer groupId) {
    restClient
        .delete()
        .uri(restBaseUrl(course) + "/groups/" + groupId)
        .header("Authorization", bearer(course))
        .retrieve()
        .toBodilessEntity();
  }

  /**
   * Adds a user to a Canvas group.
   *
   * @param course the course, which must be linked to Canvas
   * @param groupId the numeric Canvas id of the group
   * @param userId the numeric Canvas id of the user
   */
  public void addCanvasGroupMember(
      @HasLinkedCanvasCourse Course course, Integer groupId, Integer userId) {
    restClient
        .post()
        .uri(restBaseUrl(course) + "/groups/" + groupId + "/memberships")
        .header("Authorization", bearer(course))
        .contentType(MediaType.APPLICATION_JSON)
        .body(Map.of("user_id", userId))
        .retrieve()
        .toBodilessEntity();
  }

  /**
   * Removes a user from a Canvas group.
   *
   * @param course the course, which must be linked to Canvas
   * @param groupId the numeric Canvas id of the group
   * @param userId the numeric Canvas id of the user
   */
  public void removeCanvasGroupMember(
      @HasLinkedCanvasCourse Course course, Integer groupId, Integer userId) {
    restClient
        .delete()
        .uri(restBaseUrl(course) + "/groups/" + groupId + "/users/" + userId)
        .header("Authorization", bearer(course))
        .retrieve()
        .toBodilessEntity();
  }

  /**
   * Fetches every edge of the course's student enrollment connection, following pagination.
   *
   * @param course the course
   * @param nodeFields the GraphQL fields to select on each user node
   * @return all edges, in Canvas order
   */
  private List<JsonNode> studentEdges(Course course, String nodeFields) {
    String query =
        "query GetStudents($courseId: ID!, $first: Int!, $after: String) {"
            + " course(id: $courseId) {"
            + " usersConnection(filter: {enrollmentTypes: StudentEnrollment}, first: $first,"
            + " after: $after) { edges { node { "
            + nodeFields
            + " } } pageInfo { hasNextPage endCursor } } } }";
    return allEdges(
        authedClient(course),
        query,
        Map.of("courseId", course.getCanvasCourseId()),
        "course.usersConnection",
        null);
  }

  /**
   * Fetches the members of one group that did not fit in the first page of the group set query.
   *
   * @param client the authenticated client
   * @param groupId the numeric Canvas id of the group
   * @param after the end cursor of the page already read
   * @return the remaining edges
   */
  private List<JsonNode> remainingGroupMemberEdges(
      HttpSyncGraphQlClient client, Integer groupId, String after) {
    // language=GraphQL
    String query =
        """
            query GetGroupMembers($groupId: ID!, $first: Int!, $after: String) {
              legacyNode(_id: $groupId, type: Group) {
                ... on Group {
                  membersConnection(first: $first, after: $after) {
                    edges {
                      node {
                        user {
                          _id
                          email
                        }
                      }
                    }
                    pageInfo {
                      hasNextPage
                      endCursor
                    }
                  }
                }
              }
            }
            """;
    return allEdges(
        client,
        query,
        Map.of("groupId", groupId.toString()),
        "legacyNode.membersConnection",
        after);
  }

  /**
   * Reads a paginated connection to the end. The query must declare {@code $first: Int!} and {@code
   * $after: String}, pass them to the connection, and select {@code pageInfo { hasNextPage
   * endCursor }} on it.
   *
   * @param client the authenticated client
   * @param query the query
   * @param variables the query's other variables
   * @param connectionPath the path of the connection in the response
   * @param after the cursor to start after, or null to start at the beginning
   * @return every edge from {@code after} to the end, in order
   */
  private static List<JsonNode> allEdges(
      HttpSyncGraphQlClient client,
      String query,
      Map<String, Object> variables,
      String connectionPath,
      String after) {
    List<JsonNode> edges = new ArrayList<>();
    while (true) {
      GraphQlClient.RequestSpec request =
          client.document(query).variables(variables).variable("first", PAGE_SIZE);
      if (after != null) {
        request = request.variable("after", after);
      }
      JsonNode connection = request.retrieveSync(connectionPath).toEntity(JsonNode.class);
      connection.path("edges").forEach(edges::add);
      JsonNode pageInfo = connection.path("pageInfo");
      if (!pageInfo.path("hasNextPage").asBoolean()) {
        return edges;
      }
      after = pageInfo.path("endCursor").asText();
    }
  }

  /**
   * The GraphQL field that looks up a group set by the given id. Canvas's {@code node(id:)} takes
   * only the GraphQL relay id (e.g. "R3JvdXBTZXQtMTAx"); a plain numeric id, as shown in Canvas
   * URLs and by the Canvas REST API, must go through {@code legacyNode}. Both forms are accepted so
   * that instructors can paste either.
   *
   * @param groupSetId a relay id or a numeric id
   * @return the field selector, without its selection set
   */
  static String groupSetSelector(String groupSetId) {
    if (groupSetId.matches("\\d+")) {
      return "legacyNode(_id: $groupId, type: GroupSet)";
    }
    return "node(id: $groupId)";
  }

  private HttpSyncGraphQlClient authedClient(Course course) {
    return graphQlClient
        .mutate()
        .header("Authorization", bearer(course))
        .url(course.getSchool().getCanvasImplementation())
        .build();
  }

  private String bearer(Course course) {
    return "Bearer " + canvasApiTokenSecurityService.decrypt(course.getCanvasApiToken());
  }

  /**
   * The Canvas REST API base for the course's school, derived from the GraphQL endpoint: e.g.
   * https://ucsb.instructure.com/api/graphql becomes https://ucsb.instructure.com/api/v1.
   */
  private static String restBaseUrl(Course course) {
    return course.getSchool().getCanvasImplementation().replace("/api/graphql", "/api/v1");
  }
}