Introduce Cadet API v2 (#721)

* Update `/assets` endpoint (#713)

* Assets: remove role validation in model

* AssetsController: update API endpoint and validation

The endpoint is updated to `/v2/admin/assets`, and validation is
performed within the router instead.

* Shift to `AdminAssetsController`

* Rename `AdminAssetsController` to `.exs`

* Assets: switch to `case` instead of `with`

* (1) Clearer Swagger documentation in Grading (2) Code documentation cleaup in auth_controller

* Notifications changed to plural throughout

* Settings swagger docs cleanup

* User docs typo fix

* CI fix formatting

* Update `/settings` endpoint (#722)

* `/auth`: shift `/auth` to `/auth/login`

* `/devices`: fix typo and shift to v2

* Update `/grading` endpoint (#727)

* shift role validation for Settings

* shift Grading controller to AdminGrading

* fix formatting and add details to docs

Co-authored-by: Benjamin Tan <benjamin@dev.ofcr.se>

* Rename `assets_controller_test` to `admin_assets_controller_test`

* update swagger docs for /grading

* Update `/assessments` endpoint (#729)

* `/assessments`: split out separate `/admin` endpoint

* Consistently use `/assessments/:assessmentid`

* Merge `/admin/assessments/:assessmentid/{update,publish}` endpoints

* Quick swagger docs fix for `AdminAssessmentsController`

* Format code via `mix format`

* Formatting fix

* `/assessments/{assessmentid}/submit`: shift role validation to controller

* Add more guards

* `/assessments/question/{questionid}/submit`: shift role validation to AnswerController

* clean up some docs

* Modify `AnswerController#submit` path

* Assessments: remove unused definitions

* Remove leftover unused route

* Split `AssesmentsController#unlock` out of `AssessmentsController#show`

`AssesmentsController#unlock` unlocks password-protected assessments and
creates a Submission for them, following which the assessments do not
require requests with the password.

* Fix formatting issues

* `/assessments`: split out separate `/admin` endpoint

* Consistently use `/assessments/:assessmentid`

* Merge `/admin/assessments/:assessmentid/{update,publish}` endpoints

* Quick swagger docs fix for `AdminAssessmentsController`

* Format code via `mix format`

* `/assessments/{assessmentid}/submit`: shift role validation to controller

* Add more guards

* `/assessments/question/{questionid}/submit`: shift role validation to AnswerController

* clean up some docs

* Modify `AnswerController#submit` path

* Assessments: remove unused definitions

* Remove leftover unused route

* Split `AssesmentsController#unlock` out of `AssessmentsController#show`

`AssesmentsController#unlock` unlocks password-protected assessments and
creates a Submission for them, following which the assessments do not
require requests with the password.

* Fix formatting issues

* formatting

* Update per PR feedback

* Remove unused variable

Co-authored-by: qreoct <9080974+qreoct@users.noreply.github.com>

* Change to v2 API throughout

* Fix Swagger references

* AdminGradingControllerTest: Add swagger path definition

* Remove duplicated route

* Rename file as per convention

* Swagger documentation: Switch to enums for string values

* /auth/login: shift parameters to query string in docs

* UserController: add an empty UserGameStates map to the schema

* Add comments to clarify invalid OpenAPI 2.0 types

* Swagger: shift request parameters to separate schemas

Request parameters were previously declared as separate body parameters
in the Swagger schema, which was technically invalid. For endpoints
which require more than 1 parameter, which is sent as JSON, I've created
separated schemas which represent the parameters, to make the generated
`swagger.json` more compliant.

* Story: Fix inaccurate Swagger documentation

* Shift all Swagger enums into their own schemas

This allows `swagger-typescript-api` in `cadet-frontend` to generate
TypeScript `enum`s for the corresponding type.

* Fix inaccurate types

* Update based on code review feedback

* clean up docs

* clean up docs

* Endpoints: update to mark as required

* More changes to the Swagger types

* Even more type updates

* more swagger docs consistency

* /admin/assessments: update swagger to FormData parameters

Co-authored-by: qreoct <9080974+qreoct@users.noreply.github.com>

Author: bnjmnt4n

lib/cadet/assessments/assessments.ex

@@ -1,6 +1,6 @@
 defmodule Cadet.Assessments.Library do
   @moduledoc """
-  The library entity represents a library to be used in a  question.
+  The library entity represents a library to be used in a question.
   """
   use Cadet, :model
 

lib/cadet/assessments/library.ex

@@ -5,17 +5,14 @@ defmodule Cadet.Assets.Assets do
   Assessments context contains domain logic for assets management
   for Source academy's game component
   """
-  @manage_assets_role ~w(staff admin)a
-
   @accessible_folders ~w(images locations objects avatars ui stories sfx bgm) ++
                         if(Mix.env() == :test, do: ["testFolder"], else: [])
   @accepted_file_types ~w(.jpg .jpeg .gif .png .wav .mp3 .txt)
 
-  def upload_to_s3(upload_params, folder_name, file_name, user) do
+  def upload_to_s3(upload_params, folder_name, file_name) do
     file_type = Path.extname(file_name)
 
-    with :ok <- validate_role(user.role),
-         :ok <- validate_file_name(file_name),
+    with :ok <- validate_file_name(file_name),
          :ok <- validate_folder_name(folder_name),
          :ok <- validate_file_type(file_type) do
       if object_exists?(folder_name, file_name) do
@@ -35,19 +32,21 @@ defmodule Cadet.Assets.Assets do
     end
   end
 
-  def list_assets(folder_name, user) do
-    with :ok <- validate_role(user.role),
-         :ok <- validate_folder_name(folder_name) do
-      bucket()
-      |> S3.list_objects(prefix: folder_name <> "/")
-      |> ExAws.stream!()
-      |> Enum.map(fn file -> file.key end)
+  def list_assets(folder_name) do
+    case validate_folder_name(folder_name) do
+      :ok ->
+        bucket()
+        |> S3.list_objects(prefix: folder_name <> "/")
+        |> ExAws.stream!()
+        |> Enum.map(fn file -> file.key end)
+
+      {:error, _} = error ->
+        error
     end
   end
 
-  def delete_object(folder_name, file_name, user) do
-    with :ok <- validate_role(user.role),
-         :ok <- validate_file_name(file_name),
+  def delete_object(folder_name, file_name) do
+    with :ok <- validate_file_name(file_name),
          :ok <- validate_folder_name(folder_name) do
       if object_exists?(folder_name, file_name) do
         bucket()
@@ -71,14 +70,6 @@ defmodule Cadet.Assets.Assets do
     end
   end
 
-  defp validate_role(role) do
-    if role in @manage_assets_role do
-      :ok
-    else
-      {:error, {:forbidden, "User not allowed to manage assets"}}
-    end
-  end
-
   defp validate_folder_name(folder_name) do
     if folder_name in @accessible_folders do
       :ok

lib/cadet/assets/assets.ex

@@ -0,0 +1,162 @@
+defmodule CadetWeb.AdminAssessmentsController do
+  use CadetWeb, :controller
+
+  use PhoenixSwagger
+
+  alias Cadet.Assessments
+  import Cadet.Updater.XMLParser, only: [parse_xml: 2]
+
+  def create(conn, %{"assessment" => assessment, "forceUpdate" => force_update}) do
+    file =
+      assessment["file"].path
+      |> File.read!()
+
+    result =
+      case force_update do
+        "true" -> parse_xml(file, true)
+        "false" -> parse_xml(file, false)
+      end
+
+    case result do
+      :ok ->
+        if force_update == "true" do
+          text(conn, "Force update OK")
+        else
+          text(conn, "OK")
+        end
+
+      {:ok, warning_message} ->
+        text(conn, warning_message)
+
+      {:error, {status, message}} ->
+        conn
+        |> put_status(status)
+        |> text(message)
+    end
+  end
+
+  def delete(conn, %{"assessmentid" => assessment_id}) do
+    result = Assessments.delete_assessment(assessment_id)
+
+    case result do
+      {:ok, _nil} ->
+        text(conn, "OK")
+
+      {:error, {status, message}} ->
+        conn
+        |> put_status(status)
+        |> text(message)
+    end
+  end
+
+  def update(conn, params = %{"assessmentid" => assessment_id}) when is_ecto_id(assessment_id) do
+    open_at = params |> Map.get("openAt")
+    close_at = params |> Map.get("closeAt")
+    is_published = params |> Map.get("isPublished")
+
+    updated_assessment =
+      if is_nil(is_published) do
+        %{}
+      else
+        %{:is_published => is_published}
+      end
+
+    with {:ok, assessment} <- check_dates(open_at, close_at, updated_assessment),
+         {:ok, _nil} <- Assessments.update_assessment(assessment_id, assessment) do
+      text(conn, "OK")
+    else
+      {:error, {status, message}} ->
+        conn
+        |> put_status(status)
+        |> text(message)
+    end
+  end
+
+  defp check_dates(open_at, close_at, assessment) do
+    if is_nil(open_at) and is_nil(close_at) do
+      {:ok, assessment}
+    else
+      formatted_open_date = elem(DateTime.from_iso8601(open_at), 1)
+      formatted_close_date = elem(DateTime.from_iso8601(close_at), 1)
+
+      if Timex.before?(formatted_close_date, formatted_open_date) do
+        {:error, {:bad_request, "New end date should occur after new opening date"}}
+      else
+        assessment = Map.put(assessment, :open_at, formatted_open_date)
+        assessment = Map.put(assessment, :close_at, formatted_close_date)
+
+        {:ok, assessment}
+      end
+    end
+  end
+
+  swagger_path :create do
+    post("/admin/assessments")
+
+    summary("Creates a new assessment or updates an existing assessment")
+
+    security([%{JWT: []}])
+
+    consumes("multipart/form-data")
+
+    parameters do
+      assessment(:formData, :file, "Assessment to create or update", required: true)
+      forceUpdate(:formData, :boolean, "Force update", required: true)
+    end
+
+    response(200, "OK")
+    response(400, "XML parse error")
+    response(403, "Forbidden")
+  end
+
+  swagger_path :delete do
+    PhoenixSwagger.Path.delete("/admin/assessments/{assessmentId}")
+
+    summary("Deletes an assessment")
+
+    security([%{JWT: []}])
+
+    parameters do
+      assessmentId(:path, :integer, "Assessment ID", required: true)
+    end
+
+    response(200, "OK")
+    response(403, "Forbidden")
+  end
+
+  swagger_path :update do
+    post("/admin/assessments/{assessmentId}")
+
+    summary("Updates an assessment")
+
+    security([%{JWT: []}])
+
+    consumes("application/json")
+
+    parameters do
+      assessmentId(:path, :integer, "Assessment ID", required: true)
+
+      assessment(:body, Schema.ref(:AdminUpdateAssessmentPayload), "Updated assessment details",
+        required: true
+      )
+    end
+
+    response(200, "OK")
+    response(401, "Assessment is already opened")
+    response(403, "Forbidden")
+  end
+
+  def swagger_definitions do
+    %{
+      # Schemas for payloads to modify data
+      AdminUpdateAssessmentPayload:
+        swagger_schema do
+          properties do
+            closeAt(:string, "Open date", required: false)
+            openAt(:string, "Close date", required: false)
+            isPublished(:boolean, "Whether the assessment is published", required: false)
+          end
+        end
+    }
+  end
+end

lib/cadet_web/admin_controllers/admin_assessments_controller.ex

@@ -1,11 +1,11 @@
-defmodule CadetWeb.AssetsController do
+defmodule CadetWeb.AdminAssetsController do
   use CadetWeb, :controller
 
   use PhoenixSwagger
   alias Cadet.Assets.Assets
 
   def index(conn, _params = %{"foldername" => foldername}) do
-    case Assets.list_assets(foldername, conn.assigns.current_user) do
+    case Assets.list_assets(foldername) do
       {:error, {status, message}} -> conn |> put_status(status) |> text(message)
       assets -> render(conn, "index.json", assets: assets)
     end
@@ -15,7 +15,7 @@ defmodule CadetWeb.AssetsController do
   def delete(conn, _params = %{"foldername" => foldername, "filename" => filename}) do
     filename = Enum.join(filename, "/")
 
-    case Assets.delete_object(foldername, filename, conn.assigns.current_user) do
+    case Assets.delete_object(foldername, filename) do
       {:error, {status, message}} -> conn |> put_status(status) |> text(message)
       _ -> conn |> put_status(204) |> text('')
     end
@@ -28,7 +28,7 @@ defmodule CadetWeb.AssetsController do
       }) do
     filename = Enum.join(filename, "/")
 
-    case Assets.upload_to_s3(upload_params, foldername, filename, conn.assigns.current_user) do
+    case Assets.upload_to_s3(upload_params, foldername, filename) do
       {:error, {status, message}} -> conn |> put_status(status) |> text(message)
       resp -> render(conn, "show.json", resp: resp)
     end
@@ -60,12 +60,12 @@ defmodule CadetWeb.AssetsController do
   end
 
   swagger_path :index do
-    get("/assets/{foldername}")
+    get("/admin/assets/{folderName}")
 
     summary("Get a list of all assets in a folder")
 
     parameters do
-      foldername(:path, :string, "Folder name", required: true)
+      folderName(:path, :string, "Folder name", required: true)
     end
 
     security([%{JWT: []}])
@@ -78,35 +78,33 @@ defmodule CadetWeb.AssetsController do
   end
 
   swagger_path :delete do
-    PhoenixSwagger.Path.delete("/assets/{foldername}/{filename}")
+    PhoenixSwagger.Path.delete("/admin/assets/{folderName}/{fileName}")
 
     summary("Delete a file from an asset folder")
 
     parameters do
-      foldername(:path, :string, "Folder name", required: true)
+      folderName(:path, :string, "Folder name", required: true)
 
-      filename(:path, :string, "File path in folder, which may contain subfolders", required: true)
+      fileName(:path, :string, "File path in folder, which may contain subfolders", required: true)
     end
 
     security([%{JWT: []}])
 
-    produces("application/json")
-
     response(204, "OK")
     response(400, "Invalid folder name, file name or file type")
     response(403, "User is not allowed to manage assets")
     response(404, "File not found")
   end
 
   swagger_path :upload do
-    post("/assets/{foldername}/{filename}")
+    post("/admin/assets/{folderName}/{fileName}")
 
     summary("Upload a file to an asset folder")
 
     parameters do
-      foldername(:path, :string, "Folder name", required: true)
+      folderName(:path, :string, "Folder name", required: true)
 
-      filename(:path, :string, "File path in folder, which may contain subfolders", required: true)
+      fileName(:path, :string, "File path in folder, which may contain subfolders", required: true)
     end
 
     security([%{JWT: []}])

lib/cadet_web/controllers/assets_controller.ex renamed to lib/cadet_web/admin_controllers/admin_assets_controller.ex

@@ -100,7 +100,7 @@ defmodule CadetWeb.AdminGoalsController do
   end
 
   swagger_path :delete do
-    PhoenixSwagger.Path.delete("/admin/goals/{id}")
+    PhoenixSwagger.Path.delete("/admin/goals/{uuid}")
 
     summary("Deletes a goal")
     security([%{JWT: []}])