WIP: Skills question endpoint

[barna-isaac]

This adds a new endpoint, meant for Anvil apps to record new question attempts.

For now, the new endpoint:

• is not rate limited
• does not create entries in the logged_events table
  I plan to implement this functionality later, when the feature is more mature.

Testing

I've manually tested that attempts are recorded on my own machine, by visiting http://localhost:8004/pages/app_page_mental_maths_overall, opening the JS console, and intercepting one of the messages emitted by the app:

window.addEventListener('message', e => {
    if(e.origin === 'https://cuta66namfmobkjs.anvil.app' && e.data.type === 'SUBMISSION_MARKED') {
        console.log('got anvil message', e.data);
    }
});

Then, a request can be posted with the following curl:

curl --location 'http://localhost:8080/isaac-api/api/skills/app_page_mental_maths_overall_recorded/answer' \
--header ' __Host-SEGUE_AUTH_COOKIE=<your_cookie_here>\
--header 'Content-Type: application/json' \
--data '{
    "payload": "<from_message>",
    "hmac": "<from_message>"
}'

Overview of changes

To help with the review, here is a high-level list of changes:
17 changed files in total.

• 11 changes to the implementation

  • 2 new DTO's 1 new Exception. InvalidAnvilMarkingRequestException.java, AnvilMarkingRequestDTO.java, AnvilPayloadDTO.java. Two DTO's because the HMAC'ed payload is first validated, and only then parsed.
  • For the implementation, 4 files: SkillsFacade.java, SkillsManager.java, ISkillsAttemptManager.java, PgSkillsAttemptManager.java, mirroring the Manager <-> IPersistenceManager <-> PersistenceManager pattern for question attempts
  • 4 configuration files, Constants.java, IsaacApplicationRegister.java, SegueGuiceConfigurationModule.java, and a migration in 2026-06-skills_question_attempts.sql

• 6 changes to testing

  • 3 files for testing the new endpoint: SkillsFacadeIT.java, postgres-rutherford-create-script.sql to apply the new db schema for testing, and segue-integration-test-config.yaml so the new config value is set for test.
  • 4 files for changes to the test framework. ElasticSearchTestHelper.java, QuestionFacadeIT.java, IsaacIntegrationTestWithRest.java because I've extracted a helper method from QuestionFacadeIT, so the same method can be reused in the new tests. The method lets us add content to elastic search. Further, the test server now applies the same exception handlers as the live app.

---

Pull Request Check List

• Unit Tests & Regression Tests Added (Optional)
• Removed Unnecessary Logs/System.Outs/Comments/TODOs
• Added enough Logging to monitor expected behaviour change
• Security - Injection - everything run by an interpreter (SQL, OS...) is either validated or escaped
• Security - Data Exposure - PII is not stored or sent unencrypted
• Security - Data Exposure - Test any altered or created endpoints using swagger
• Security - Access Control - Check authorisation on every new endpoint
• Security - New dependency - configured sensibly not relying on defaults
• Security - New dependency - Searched for any know vulnerabilities
• Security - New dependency - Signed up team to mailing list
• Security - New dependency - Added to dependency list
• DB schema changes - postgres-rutherford-create-script updated
• DB schema changes - upgrade script created matching create script
• Updated Release Procedure & Documentation (& Considered Implications to Previous Versions)
• Peer-Reviewed

[codecov]

Codecov Report

❌ Patch coverage is 87.80488% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 40.62%. Comparing base (45bb1b3) to head (4191922).
⚠️ Report is 18 commits behind head on main.

Files with missing lines	Patch %	Lines
.../java/uk/ac/cam/cl/dtg/isaac/api/SkillsFacade.java	87.17%	3 Missing and 2 partials ⚠️
...e/configuration/SegueGuiceConfigurationModule.java	20.00%	4 Missing ⚠️
.../isaac/configuration/IsaacApplicationRegister.java	0.00%	2 Missing ⚠️
...c/cam/cl/dtg/isaac/dao/PgSkillsAttemptManager.java	90.47%	1 Missing and 1 partial ⚠️
...va/uk/ac/cam/cl/dtg/isaac/dto/AnvilPayloadDTO.java	92.00%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #798      +/-   ##
==========================================
+ Coverage   40.25%   40.62%   +0.37%     
==========================================
  Files         547      553       +6     
  Lines       23810    23937     +127     
  Branches     2901     2909       +8     
==========================================
+ Hits         9584     9725     +141     
+ Misses      13323    13306      -17     
- Partials      903      906       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.