xAPI 2.0 Support

Makefile

@@ -2,7 +2,7 @@
 
 # Version of LRS Admin UI to use
 
-LRS_ADMIN_UI_VERSION ?= v0.2.5
+LRS_ADMIN_UI_VERSION ?= v0.2.6
 LRS_ADMIN_UI_LOCATION ?= https://github.com/yetanalytics/lrs-admin-ui/releases/download/${LRS_ADMIN_UI_VERSION}/lrs-admin-ui.zip
 LRS_ADMIN_ZIPFILE ?= lrs-admin-ui-${LRS_ADMIN_UI_VERSION}.zip
 

deps.edn

@@ -53,12 +53,12 @@
   xyz.capybara/clamav-client                    {:mvn/version "2.1.2"}
   ;; Yet Analytics deps
   com.yetanalytics/lrs
-  {:mvn/version "1.3.1"
+  {:mvn/version "1.4.0"
    :exclusions  [org.clojure/clojure
                  org.clojure/clojurescript
                  com.yetanalytics/xapi-schema]}
   com.yetanalytics/xapi-schema
-  {:mvn/version "1.4.0"
+  {:mvn/version "1.4.1"
    :exclusions  [org.clojure/clojure
                  org.clojure/clojurescript]}
   com.yetanalytics/colossal-squuid
@@ -72,7 +72,7 @@
    :exclusions  [org.clojure/clojure
                  buddy/buddy-sign]}
   com.yetanalytics/lrs-reactions
-  {:mvn/version "0.0.1"
+  {:mvn/version "0.0.3"
    :exclusions  [org.clojure/clojure]}
   com.yetanalytics/gen-openapi
   {:mvn/version "0.0.4"
@@ -136,7 +136,7 @@
                   :git/sha "3f288f1f16d167723ad87cc35b1dfee3c1681e10"}
                  com.yetanalytics.lrs/test-runner
                  {:git/url    "https://github.com/yetanalytics/lrs-test-runner.git"
-                  :git/sha    "8bd5be7816288e85f5c07fc11bf8cf53667e72da"
+                  :git/sha    "1891bb5c8802a397ffaee86d336ee95d71cc1a4d"
                   :exclusions [org.clojure/data.json]}
                  com.yetanalytics/datasim
                  {:mvn/version "0.4.4"

doc/env_vars.md

@@ -110,6 +110,9 @@ The following options are used for advanced database performance tuning and may
 | `LRSQL_STMT_RETRY_BUDGET`       | `stmtRetryBudget`       | The max amount of time allowed for statement POST transaction retries before failing (ms).                                                                                                                                               | `1000`                                                                                |
 | `LRSQL_ENABLE_REACTIONS`        | `enableReactions`       | Whether or not to enable statement reactions.                                                                                                                                                                                            | `false`                                                                               |
 | `LRSQL_REACTION_BUFFER_SIZE`    | `reactionBufferSize`    | Number of pending reactions to allow. Additional reactions will be dropped with a warning message.                                                                                                                                       | `10000`                                                                               |
+| `LRSQL_REACTION_VERSION`        | `reactionVersion`       | The xAPI version used when the reactor emits statements. Must be either `1.0.3` or `2.0.0`.                                                                                                                                             | `1.0.3`                                                                               |
+| `LRSQL_SUPPORTED_VERSIONS`      | `supportedVersions`     | A comma-separated list of supported LRS versions. This is used to validate incoming requests and ensure compatibility.                                                                                                                  | `1.0.3,2.0.0`                                                                          |
+| `LRSQL_ENABLE_STRICT_VERSION`   | `enableStrictVersion`   | Whether or not to enable strict versioning. When enabled, GET requests for statements using a 1.0.3 header will convert 2.0.0 statements by removing or normalizing fields.                                                                 | `false`                                                                               |
 
 _NOTE:_ `LRSQL_STMT_RETRY_LIMIT` and `LRSQL_STMT_RETRY_BUDGET` are used to mitigate a rare scenario where specific Actors or Activities are updated many times in large concurrent batches. In this situation the DBMS can encounter locking and these settings are used to allow retries that eventually write all the conflicting transactions, but may incur performance degradation. If you are experiencing this situation the first step would be to look at why your data needs to rewrite specific Actors or Activities rapidly with different values, which could potentially solve it at the source. If the issue cannot be avoided by data design alone, another possible solution is reducing batch sizes to decrease or eliminate locks. As a last resort, increasing these settings will at least ensure the statements get written but as mentioned may incur a slowdown in concurrent throughput.
 

resources/lrsql/config/prod/default/lrs.edn

@@ -13,4 +13,7 @@
  :stmt-retry-limit        #or [#env LRSQL_STMT_RETRY_LIMIT 10]
  :stmt-retry-budget       #or [#env LRSQL_STMT_RETRY_BUDGET 1000]
  :enable-reactions        #boolean #or [#env LRSQL_ENABLE_REACTIONS false]
- :reaction-buffer-size    #long #or [#env LRSQL_REACTION_BUFFER_SIZE 10000]}
+ :reaction-buffer-size    #long #or [#env LRSQL_REACTION_BUFFER_SIZE 10000]
+ :reaction-version        #or [#env LRSQL_REACTION_VERSION "1.0.3"]
+ :supported-versions      #or [#env LRSQL_SUPPORTED_VERSIONS "1.0.3,2.0.0"]
+ :enable-strict-version   #boolean #or [#env LRSQL_ENABLE_STRICT_VERSION false]}

resources/lrsql/config/test/default/lrs.edn

@@ -13,4 +13,7 @@
  :stmt-retry-limit        20
  :stmt-retry-budget       10000
  :enable-reactions        true
- :reaction-buffer-size    10000}
+ :reaction-buffer-size    10000
+ :reaction-version        "1.0.3"
+ :supported-versions      "1.0.3,2.0.0"
+ :enable-strict-version   false}

src/db/mariadb/lrsql/mariadb/record.clj

@@ -68,11 +68,10 @@
     (create-credential-table! tx)
     (create-credential-to-scope-table! tx)
     (create-blocked-jwt-table! tx))
-  (-update-all! [_ _tx]
-    ; MariaDB is the latest database to get a SQl-LRS implementation, so no migrations are needed.
-    ; In the future migrations will go here.
-    )
-
+  (-update-all! [_ tx]
+    (when-not (= 1 (:has_context_agent (query-statement-to-actor-usage-enum-has-context-actors tx)))
+      (alter-statement-to-actor-usage-enum-add-context-actors! tx)))
+
   bp/BackendUtil
   (-txn-retry? [_ ex]
     (and (instance? java.sql.SQLException ex)
@@ -201,7 +200,7 @@
   ;;;; So we don't actually store the JWT; we just store a (shorter) hash of it.  
   ;;;; Operations that don't interact with the jwt obviously don't need to hash it.
   ;;;;
-  
+
   bp/JWTBlocklistBackend
   (-insert-blocked-jwt! [_ tx input]
     (insert-blocked-jwt! tx (update input :jwt md/sha256-base64)))

src/db/mariadb/lrsql/mariadb/sql/ddl.sql

@@ -273,3 +273,34 @@ CREATE TABLE IF NOT EXISTS blocked_jwt (
   one_time_id CHAR(36) UNIQUE,
   KEY blocked_jwt_evict_time_idx (evict_time)
 );
+
+/* Migration 2025-09-26 - Add ContextAgent, ContextGroup, SubContextAgent, SubContextGroup to statement_to_actor usage enum */
+
+-- :name query-statement-to-actor-usage-enum-has-context-actors
+-- :command :query
+-- :result :one
+-- :doc Query to see if the `statement_to_actor.usage` column has ContextAgent in its enum.
+SELECT EXISTS (
+    SELECT 1
+    FROM INFORMATION_SCHEMA.COLUMNS
+    WHERE TABLE_NAME = 'statement_to_actor'
+      AND COLUMN_NAME = 'usage'
+      AND FIND_IN_SET('ContextAgent', REPLACE(REPLACE(COLUMN_TYPE, 'enum(', ''), ')', '')) > 0
+) AS has_context_agent;
+
+-- :name alter-statement-to-actor-usage-enum-add-context-actors!
+-- :command :execute
+-- :doc Change the enum datatype of the `statement_to_actor.usage` column to add ContextAgent, ContextGroup, SubContextAgent, and SubContextGroup.
+ALTER TABLE statement_to_actor MODIFY COLUMN `usage` ENUM ('Actor',
+                     'Object',
+                     'Authority',
+                     'Instructor',
+                     'Team',
+                     'SubActor',
+                     'SubObject',
+                     'SubInstructor',
+                     'SubTeam',
+                     'ContextAgent',
+                     'ContextGroup',
+                     'SubContextAgent',
+                     'SubContextGroup') NOT NULL;

src/db/postgres/lrsql/postgres/record.clj

@@ -84,7 +84,9 @@
     (create-blocked-jwt-table! tx)
     (alter-blocked-jwt-add-one-time-id! tx)
     (alter-lrs-credential-add-label! tx)
-    (alter-lrs-credential-add-is-seed! tx))
+    (alter-lrs-credential-add-is-seed! tx)
+    (when-not (some? (query-statement-to-actor-usage-enum-has-context-actors tx))
+      (alter-statement-to-actor-usage-enum-add-context-actors! tx)))
 
   bp/BackendUtil
   (-txn-retry? [_ ex]

src/db/postgres/lrsql/postgres/sql/ddl.sql

@@ -525,3 +525,24 @@ ALTER TABLE lrs_credential ADD COLUMN IF NOT EXISTS label TEXT;
 -- :command :execute
 -- :doc Add the `is_seed` column to the `lrs_credential` table if it does not exist.
 ALTER TABLE lrs_credential ADD COLUMN IF NOT EXISTS is_seed BOOLEAN;
+
+/* Migration 2025-09-26 - Add ContextAgent, ContextGroup, SubContextAgent, SubContextGroup to statement_to_actor usage enum */
+
+-- :name query-statement-to-actor-usage-enum-has-context-actors
+-- :command :query
+-- :result :one
+-- :doc Query to see if the `statement_to_actor.usage` column has ContextAgent in its enum.
+SELECT 1
+WHERE enum_range(NULL::actor_usage_enum)::TEXT[]
+  @> ARRAY['ContextAgent'];
+
+-- :name alter-statement-to-actor-usage-enum-add-context-actors!
+-- :command :execute
+-- :doc Change the enum datatype of the `statement_to_actor.usage` column to add ContextAgent, ContextGroup, SubContextAgent, and SubContextGroup.
+ALTER TABLE IF EXISTS statement_to_actor ALTER COLUMN usage TYPE VARCHAR(255);
+DROP TYPE IF EXISTS actor_usage_enum;
+CREATE TYPE actor_usage_enum AS ENUM (
+    'Actor', 'Object', 'Authority', 'Instructor', 'Team',
+    'SubActor', 'SubObject', 'SubInstructor', 'SubTeam',
+    'ContextAgent', 'ContextGroup', 'SubContextAgent', 'SubContextGroup');
+ALTER TABLE IF EXISTS statement_to_actor ALTER COLUMN usage TYPE actor_usage_enum USING (usage::actor_usage_enum);

src/db/sqlite/lrsql/sqlite/record.clj

@@ -124,6 +124,8 @@
       (alter-lrs-credential-add-label! tx))
     (when-not (some? (query-lrs-credential-is-seed-exists tx))
       (alter-lrs-credential-add-is-seed! tx))
+    (when-not (some? (query-statement-to-actor-usage-enum-has-context-actors tx))
+      (update-schema-simple! tx alter-statement-to-actor-usage-enum-add-context-actors!))
     (log/infof "sqlite schema_version: %d"
                (:schema_version (query-schema-version tx))))
 

src/db/sqlite/lrsql/sqlite/sql/ddl.sql

@@ -581,3 +581,38 @@ SELECT 1 FROM pragma_table_info('lrs_credential') WHERE name = 'is_seed'
 -- :command :execute
 -- :doc Add the `is_seed` column to the `lrs_credential` table.
 ALTER TABLE lrs_credential ADD COLUMN is_seed INTEGER; -- boolean type
+
+/* Migration 2025-09-26 - Add ContextAgent, ContextGroup, SubContextAgent, SubContextGroup to statement_to_actor usage enum */
+
+-- :name query-statement-to-actor-usage-enum-has-context-actors
+-- :command :query
+-- :result :one
+-- :doc Query to see if the `statement_to_actor.usage` column has ContextAgent in its enum.
+SELECT 1
+FROM sqlite_master
+WHERE type = 'table'
+  AND name = 'statement_to_actor'
+  AND sql LIKE '%ContextAgent%';
+
+-- :name alter-statement-to-actor-usage-enum-add-context-actors!
+-- :command :execute
+-- :doc Change the enum datatype of the `statement_to_actor.usage` column to add ContextAgent, ContextGroup, SubContextAgent, and SubContextGroup.
+UPDATE sqlite_schema
+SET sql = 'CREATE TABLE statement_to_actor (
+  id           TEXT NOT NULL PRIMARY KEY, -- uuid
+  statement_id TEXT NOT NULL,             -- uuid
+  usage        TEXT NOT NULL CHECK (
+                 usage IN (''Actor'', ''Object'', ''Authority'', ''Instructor'', ''Team'',
+                           ''SubActor'', ''SubObject'', ''SubInstructor'', ''SubTeam'',
+                           ''ContextAgent'', ''ContextGroup'', ''SubContextAgent'', ''SubContextGroup'')
+                                   ),     -- enum
+  actor_ifi    TEXT NOT NULL,             -- ifi string
+  actor_type   TEXT NOT NULL CHECK (
+                 actor_type IN (''Agent'', ''Group'')
+                 ),                       -- enum
+
+  FOREIGN KEY (statement_id) REFERENCES xapi_statement(statement_id)
+    ON DELETE CASCADE,
+  FOREIGN KEY (actor_ifi, actor_type) REFERENCES actor(actor_ifi, actor_type)
+)'
+WHERE type = 'table' AND name = 'statement_to_actor';

src/main/lrsql/admin/interceptors/reaction.clj

@@ -5,7 +5,8 @@
             [lrsql.admin.protocol :as adp]
             [lrsql.spec.reaction :as rs]
             [lrsql.util.reaction :as ru]
-            [lrsql.util :as u]))
+            [lrsql.util :as u]
+            [xapi-schema.spec :as xs]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Validation Interceptors
@@ -21,16 +22,19 @@
             (get-in ctx [:request :json-params])
             params (cond-> raw-params
                      ruleset
-                     (update :ruleset ru/json->ruleset))]
-        (if-some [err (s/explain-data rs/create-reaction-params-spec params)]
-          ;; Invalid parameters - Bad Request
-          (assoc (chain/terminate ctx)
-                 :response
-                 {:status 400
-                  :body   {:error (format "Invalid parameters:\n%s"
-                                          (-> err s/explain-out with-out-str))}})
-          ;; Valid params - continue
-          (assoc ctx ::data params))))}))
+                     (update :ruleset ru/json->ruleset))
+            lrs (:com.yetanalytics/lrs ctx)
+            xapi-version (get-in lrs [:config :reaction-version] "1.0.3")]
+        (binding [xs/*xapi-version* xapi-version]
+          (if-some [err (s/explain-data rs/create-reaction-params-spec params)]
+            ;; Invalid parameters - Bad Request
+            (assoc (chain/terminate ctx)
+                   :response
+                   {:status 400
+                    :body   {:error (format "Invalid parameters:\n%s"
+                                            (-> err s/explain-out with-out-str))}})
+            ;; Valid params - continue
+            (assoc ctx ::data params)))))}))
 
 (def validate-update-reaction-params
   "Validate valid params for reaction update."
@@ -44,17 +48,20 @@
                        ru/json->input
                        (update :reaction-id u/str->uuid)
                        (cond->
-                         ruleset
-                         (update :ruleset ru/json->ruleset)))]
-        (if-some [err (s/explain-data rs/update-reaction-params-spec params)]
-          ;; Invalid parameters - Bad Request
-          (assoc (chain/terminate ctx)
-                 :response
-                 {:status 400
-                  :body   {:error (format "Invalid parameters:\n%s"
-                                          (-> err s/explain-out with-out-str))}})
-          ;; Valid params - continue
-          (assoc ctx ::data params))))}))
+                        ruleset
+                         (update :ruleset ru/json->ruleset)))
+            lrs (:com.yetanalytics/lrs ctx)
+            xapi-version (get-in lrs [:config :reaction-version] "1.0.3")]
+        (binding [xs/*xapi-version* xapi-version]
+          (if-some [err (s/explain-data rs/update-reaction-params-spec params)]
+            ;; Invalid parameters - Bad Request
+            (assoc (chain/terminate ctx)
+                   :response
+                   {:status 400
+                    :body   {:error (format "Invalid parameters:\n%s"
+                                            (-> err s/explain-out with-out-str))}})
+            ;; Valid params - continue
+            (assoc ctx ::data params)))))}))
 
 (def validate-delete-reaction-params
   "Validate valid params for reaction delete."

src/main/lrsql/admin/interceptors/ui.clj

@@ -46,7 +46,8 @@
     :enter
     (fn get-env [ctx]
       (let [{url-prefix       ::i/path-prefix
-             oidc-env         ::oidc-i/admin-env} ctx]
+             oidc-env         ::oidc-i/admin-env
+             lrs              :com.yetanalytics/lrs} ctx]
         (assoc ctx
                :response
                {:status 200
@@ -63,7 +64,9 @@
                           :admin-language-code       admin-language-code
                           :custom-language           (custom-language-map)
                           :stmt-get-max              stmt-get-max
-                          :auth-by-cred-id           auth-by-cred-id}
+                          :auth-by-cred-id           auth-by-cred-id
+                          :supported-versions        (:supported-versions lrs)
+                          :reaction-version          (get-in lrs [:config :reaction-version])}
                    (and no-val?
                         (not-empty no-val-logout-url))
                    (assoc :no-val-logout-url no-val-logout-url))