WIP: Skills question endpoint

src/main/java/uk/ac/cam/cl/dtg/isaac/api/SkillsFacade.java

@@ -0,0 +1,119 @@
+package uk.ac.cam.cl.dtg.isaac.api;
+
+import com.google.inject.Inject;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import uk.ac.cam.cl.dtg.isaac.api.managers.InvalidAnvilMarkingRequestException;
+import uk.ac.cam.cl.dtg.isaac.api.managers.SkillsManager;
+import uk.ac.cam.cl.dtg.isaac.dos.content.AnvilApp;
+import uk.ac.cam.cl.dtg.isaac.dos.content.Content;
+import uk.ac.cam.cl.dtg.isaac.dto.AnvilMarkingRequestDTO;
+import uk.ac.cam.cl.dtg.isaac.dto.AnvilPayloadDTO;
+import uk.ac.cam.cl.dtg.isaac.dto.SegueErrorResponse;
+import uk.ac.cam.cl.dtg.isaac.dto.users.RegisteredUserDTO;
+import uk.ac.cam.cl.dtg.segue.api.managers.UserAccountManager;
+import uk.ac.cam.cl.dtg.segue.auth.exceptions.NoUserLoggedInException;
+import uk.ac.cam.cl.dtg.segue.dao.ILogManager;
+import uk.ac.cam.cl.dtg.segue.dao.SegueDatabaseException;
+import uk.ac.cam.cl.dtg.segue.dao.content.ContentManagerException;
+import uk.ac.cam.cl.dtg.segue.dao.content.GitContentManager;
+import uk.ac.cam.cl.dtg.util.AbstractConfigLoader;
+
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.Context;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.Status;
+
+/** Skills Facade, supports interaction related to the Isaac Skill Practice apps. */
+@Path("/skills")
+@Tag(name = "SkillsFacade", description = "/skills")
+public class SkillsFacade extends AbstractIsaacFacade {
+    private static final Logger log = LoggerFactory.getLogger(SkillsFacade.class);
+
+    private final UserAccountManager userManager;
+    private final GitContentManager contentManager;
+    private final SkillsManager skillsManager;
+
+    /**
+     * Constructor.
+     */
+    @Inject
+    public SkillsFacade(final AbstractConfigLoader properties, final UserAccountManager userManager,
+                        final ILogManager logManager, final GitContentManager contentManager,
+                        final SkillsManager skillsManager) {
+        super(properties, logManager);
+        this.userManager = userManager;
+        this.contentManager = contentManager;
+        this.skillsManager = skillsManager;
+    }
+
+    /**
+     * Endpoint that records when a user has answered a question.
+     *
+     * @param request
+     *            - the servlet request so we can find out if it is a known user.
+     * @param appId
+     *            - the app that the attempt belongs to
+     */
+    @POST
+    @Path("/{appId}/answer")
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    public Response answerQuestion(@Context final HttpServletRequest request,
+                                   @PathParam("appId") final String appId,
+                                   final AnvilMarkingRequestDTO markingRequest) {
+        try {
+            RegisteredUserDTO currentUser = userManager.getCurrentRegisteredUser(request);
+
+            if (!(hasAnvilApp(this.contentManager.getContentDOById(appId)))) {
+                var error = new SegueErrorResponse(Status.NOT_FOUND, "No app found for given id: " + appId);
+                log.warn(error.getErrorMessage());
+                return error.toResponse();
+            }
+
+            if (!skillsManager.isHmacValid(markingRequest)) {
+                var error = new SegueErrorResponse(Status.BAD_REQUEST, "Invalid HMAC signature");
+                log.warn(error.getErrorMessage());
+                return error.toResponse();
+            }
+
+            AnvilPayloadDTO payloadDTO = skillsManager.parsePayload(
+                markingRequest.getPayload(), currentUser.getId(), appId);
+            skillsManager.recordAttempt(payloadDTO);
+
+            return Response.ok(payloadDTO).build();
+        } catch (final NoUserLoggedInException e) {
+            return SegueErrorResponse.getNotLoggedInResponse();
+        } catch (final InvalidAnvilMarkingRequestException e) {
+            var error = new SegueErrorResponse(Status.BAD_REQUEST, e.getMessage());
+            log.warn(error.getErrorMessage() + ", " + e.getDetailedProblem());
+            return error.toResponse();
+        } catch (final SegueDatabaseException e) {
+            if ("Duplicate attempt ID".equals(e.getMessage())) {
+                var error = new SegueErrorResponse(Status.CONFLICT, "Duplicate attempt ID");
+                log.warn(error.getErrorMessage());
+                return error.toResponse();
+            }
+            var error = new SegueErrorResponse(Status.INTERNAL_SERVER_ERROR, "Something went wrong");
+            log.error(error.getErrorMessage());
+            return error.toResponse();
+        } catch (final ContentManagerException e) {
+            var error = new SegueErrorResponse(Status.NOT_FOUND, "Error locating the version requested", e);
+            log.error(error.getErrorMessage(), e);
+            return error.toResponse();
+        }
+    }
+
+    private boolean hasAnvilApp(final Content content) {
+        return content instanceof AnvilApp
+            || (content != null
+                && content.getChildren().stream().anyMatch(c -> c instanceof Content cc && hasAnvilApp(cc)));
+    }
+}

src/main/java/uk/ac/cam/cl/dtg/isaac/api/managers/InvalidAnvilMarkingRequestException.java

@@ -0,0 +1,19 @@
+package uk.ac.cam.cl.dtg.isaac.api.managers;
+
+/**
+ * An exception that indicates an invalid marking response was received from the external marking server.
+ */
+public class InvalidAnvilMarkingRequestException extends Exception {
+    private final String detailedProblem;
+
+    /** Constructor with message, detailed problem.*/
+    public InvalidAnvilMarkingRequestException(final String message, final String detailedProblem) {
+        super(message);
+        this.detailedProblem = detailedProblem;
+    }
+
+    /** Get detailed problem.*/
+    public String getDetailedProblem() {
+        return detailedProblem;
+    }
+}

src/main/java/uk/ac/cam/cl/dtg/isaac/api/managers/SkillsManager.java

@@ -0,0 +1,89 @@
+package uk.ac.cam.cl.dtg.isaac.api.managers;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.google.inject.Inject;
+import uk.ac.cam.cl.dtg.isaac.dto.AnvilMarkingRequestDTO;
+import uk.ac.cam.cl.dtg.isaac.dto.AnvilPayloadDTO;
+import uk.ac.cam.cl.dtg.isaac.quiz.ISkillsAttemptManager;
+import uk.ac.cam.cl.dtg.segue.api.managers.UserAuthenticationManager;
+import uk.ac.cam.cl.dtg.segue.dao.SegueDatabaseException;
+import uk.ac.cam.cl.dtg.util.AbstractConfigLoader;
+
+import java.util.Date;
+
+import static uk.ac.cam.cl.dtg.segue.api.Constants.*;
+
+/**
+ * Manager for Isaac Skills Practice app interactions.
+ */
+public class SkillsManager {
+    private static final ObjectMapper objectMapper = new ObjectMapper();
+
+    private final String hmacSecret;
+    private final ISkillsAttemptManager skillsAttemptManager;
+
+    /**
+     * Constructor.
+     *
+     * @param properties          - application configuration
+     * @param skillsAttemptManager - persistence manager for skills attempts
+     */
+    @Inject
+    public SkillsManager(final AbstractConfigLoader properties, final ISkillsAttemptManager skillsAttemptManager) {
+        this.hmacSecret = properties.getProperty(SKILLS_HMAC_SECRET);
+        this.skillsAttemptManager = skillsAttemptManager;
+    }
+
+    /**
+     * Verifies that the HMAC in the DTO matches the expected signature of the payload.
+     *
+     * @param dto - the parsed marking request
+     * @return whether the hmac was valid
+     */
+    public boolean isHmacValid(final AnvilMarkingRequestDTO dto) {
+        String expected = UserAuthenticationManager.calculateHMAC(hmacSecret, dto.getPayload());
+        return expected.equals(dto.getHmac());
+    }
+
+    /**
+     * Validates the content of the signed payload string.
+     *
+     * @param payloadStr - the payload string from the marking request
+     * @param userId     - the ID of the currently authenticated user
+     * @param appId      - the app ID from the URL, which must match the payload's skill_id
+     * @throws InvalidAnvilMarkingRequestException if the payload is malformed or any validation fails
+     */
+    public AnvilPayloadDTO parsePayload(
+        final String payloadStr, final long userId, final String appId
+    ) throws InvalidAnvilMarkingRequestException {
+        try {
+            if (payloadStr.length() > 10 * 1024) {
+                throw new InvalidAnvilMarkingRequestException("Payload too large", null);
+            }
+
+            AnvilPayloadDTO dto = objectMapper.readValue(payloadStr, AnvilPayloadDTO.class);
+            if (dto.getUserId() != userId) {
+                throw new InvalidAnvilMarkingRequestException("Payload user_id does not match session", null);
+            }
+            if (dto.getTimestamp().before(new Date(System.currentTimeMillis() - 300_000L))) {
+                throw new InvalidAnvilMarkingRequestException("Payload timestamp is outside the allowed window", null);
+            }
+            if (!dto.getSkillId().equals(appId)) {
+                throw new InvalidAnvilMarkingRequestException("Payload skill_id does not match app", null);
+            }
+            return dto;
+        } catch (final JsonProcessingException e) {
+            throw new InvalidAnvilMarkingRequestException("Invalid payload", e.getMessage());
+        }
+    }
+
+    /**
+     * Records a validated skills attempt.
+     *
+     * @param attempt - the validated payload DTO
+     */
+    public void recordAttempt(final AnvilPayloadDTO attempt) throws SegueDatabaseException {
+        skillsAttemptManager.registerSkillsAttempt(attempt);
+    }
+}

src/main/java/uk/ac/cam/cl/dtg/isaac/configuration/IsaacApplicationRegister.java

@@ -34,6 +34,7 @@
 import uk.ac.cam.cl.dtg.isaac.api.IsaacController;
 import uk.ac.cam.cl.dtg.isaac.api.PagesFacade;
 import uk.ac.cam.cl.dtg.isaac.api.QuizFacade;
+import uk.ac.cam.cl.dtg.isaac.api.SkillsFacade;
 import uk.ac.cam.cl.dtg.segue.api.AdminFacade;
 import uk.ac.cam.cl.dtg.segue.api.AuthenticationFacade;
 import uk.ac.cam.cl.dtg.segue.api.AuthorisationFacade;
@@ -123,6 +124,9 @@ public final Set<Object> getSingletons() {
             this.singletons.add(injector.getInstance(EmailFacade.class));
             this.singletons.add(injector.getInstance(QuizFacade.class));
             this.singletons.add(injector.getInstance(BookmarksFacade.class));
+            if (injector.getInstance(AbstractConfigLoader.class).getProperty(SKILLS_HMAC_SECRET) != null) {
+                this.singletons.add(injector.getInstance(SkillsFacade.class));
+            }
 
             // initialise filters
             this.singletons.add(injector.getInstance(PerformanceMonitor.class));

src/main/java/uk/ac/cam/cl/dtg/isaac/dao/PgSkillsAttemptManager.java

@@ -0,0 +1,46 @@
+package uk.ac.cam.cl.dtg.isaac.dao;
+
+import com.google.inject.Inject;
+import uk.ac.cam.cl.dtg.isaac.dto.AnvilPayloadDTO;
+import uk.ac.cam.cl.dtg.isaac.quiz.ISkillsAttemptManager;
+import uk.ac.cam.cl.dtg.segue.dao.SegueDatabaseException;
+import uk.ac.cam.cl.dtg.segue.database.PostgresSqlDb;
+
+import java.sql.SQLException;
+import java.sql.Timestamp;
+
+/** PostgreSQL-backed persistence for Anvil skills question attempts. */
+public class PgSkillsAttemptManager implements ISkillsAttemptManager {
+    private final PostgresSqlDb database;
+
+    @Inject
+    public PgSkillsAttemptManager(final PostgresSqlDb database) {
+        this.database = database;
+    }
+
+    @Override
+    public void registerSkillsAttempt(final AnvilPayloadDTO attempt) throws SegueDatabaseException {
+        try (var conn = database.getDatabaseConnection();
+             var pst = conn.prepareStatement("""
+                 INSERT INTO skills_question_attempts (
+                     id, user_id, skill_assignment_id, skill_id, subskill_id, question, question_attempt, marks,
+                     timestamp
+                 ) VALUES (?, ?, ?, ?, ?, (?::jsonb), (?::jsonb), ?, ?)""")) {
+            pst.setObject(1, attempt.getId());
+            pst.setLong(2, attempt.getUserId());
+            pst.setString(3, attempt.getSkillAssignmentId());
+            pst.setString(4, attempt.getSkillId());
+            pst.setString(5, attempt.getSubskillId());
+            pst.setString(6, attempt.getQuestion().toString());
+            pst.setString(7, attempt.getQuestionAttempt().toString());
+            pst.setInt(8, (Integer) attempt.getMarks());
+            pst.setTimestamp(9, new Timestamp(attempt.getTimestamp().getTime()));
+            pst.executeUpdate();
+        } catch (final SQLException e) {
+            if ("23505".equals(e.getSQLState())) {
+                throw new SegueDatabaseException("Duplicate attempt ID");
+            }
+            throw new SegueDatabaseException("Something went wrong saving the attempt.");
+        }
+    }
+}

src/main/java/uk/ac/cam/cl/dtg/isaac/dto/AnvilMarkingRequestDTO.java

@@ -0,0 +1,44 @@
+package uk.ac.cam.cl.dtg.isaac.dto;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * DTO representing the request received from the external Anvil marking server.
+ */
+public class AnvilMarkingRequestDTO {
+    private final String payload;
+    private final String hmac;
+
+    /**
+     * Constructor.
+     *
+     * @param payload - the signed payload from the marking server
+     * @param hmac    - the HMAC-SHA256 hex digest authenticating the payload
+     */
+    @JsonCreator
+    public AnvilMarkingRequestDTO(
+            @JsonProperty(value = "payload", required = true) final String payload,
+            @JsonProperty(value = "hmac", required = true) final String hmac) {
+        this.payload = payload;
+        this.hmac = hmac;
+    }
+
+    /**
+     * Gets the payload.
+     *
+     * @return the signed payload string
+     */
+    public String getPayload() {
+        return payload;
+    }
+
+    /**
+     * Gets the HMAC signature.
+     *
+     * @return the HMAC-SHA256 hex digest
+     */
+    public String getHmac() {
+        return hmac;
+    }
+}