Technical Specification

Overview

This document contains all the technical specifications planned, implemented, and requirements to launch the Canvas Code extension.

Architecture

We approached this with the microservice pattern to enable a more dynamic and modular application that can be easily iterated upon in later versions. This design helps us encapsulate sensitive data and manage data transfer more securely. Our backend design uses the SpringBoot framework in Java, and the frontend design uses React framework with JSX, Javascript, and webpack management to manipulate the DOM.

Figure 1. Product Architecture Diagram

To host our application, we used a Seattle University Linux server. This allows us to utilize the g++ capabilities that already exist in the Linux environment. Our program will ssh into the SU server, transparently to the customer, to establish a connection to compile and execute submissions for grading.

Oauth2/SSO Flow

To access Canvas’ API, we will follow Canvas’ OAuth2 protocol, designed to let third-party applications authenticate and perform actions on behalf of the user. This doesn’t require saving the users’ credentials. Canvas’ oAuth2 protocol, can be broken down into the four main steps listed below.

1. Register the applications with the SU Canvas instance, completed through campus administration. When approved, the developer keys (Client ID & Secret) are used to begin the token exchange.

2. Redirect the user to canvas using GET request for the redirect URL.

   1. Canvas Oauth2 URL:

GET https://<canvas-install-url>/login/oauth2/auth?client_id=XXX&response_type=code&state=YYY&redirect_uri=https://example.com/oauth2response

3. Once the redirect is approved by the user, the application will redirect the user to a login URI along with a response from the application. The response generates a code to generate an access key.

4. A POST request is sent to login/oauth2/token with the code, client secret, and client ID. Canvas will respond with an Oauth access token that will allow the chrome extension to make requests to the Canvas API.

Figure 2. User Authentication with Oauth

Scenarios

For this workflow, we have two scenarios, 1) student submission and 2) instructor/TA grading. In figures 3 and 4, we walk through the process for what the student and instructor can expect their workflows to be based on the browser extension design.

Figure 3. Code Execution Sequence Diagram for student on a custom server

Figure 4. Code Execution Sequence Diagram for Instructor on a custom server

Our end-to-end happy path scenario, involving both the student and teacher is detailed below:

1. Both the Student and Instructor/Grader will login into the extension with their Canvas accounts to grant permissions for the Canvas Code Grader extension.

2. Instructor uploads the evaluation script (makefile) for the given assignment to Canvas after creating their assignment. This is only required if the assignment must meet their code structure requirements (Ex: Hello World)

    a. The instructor must create a folder in their Files section on Canvas, named after the assignment ID associated with their created assignment.
            i.  This is found in the URL of Canvas and is a number. This is used to search for the file associated with the assignment.
    b. The evaluation script must be uploaded to the created folder and named _makefile_
            i. Students will not be able to validate their submission if the evaluation script is absent. 
   

3. Student checks to see if their code files pass the evaluation test before submitting their code:

    a. A student will see the extension injected _Evaluate_ button on the assignment page. 
    b. When clicking the Evaluate button, the student selects the files they want to validate for this assignment.
             i. If the assignment doesn’t have an instructor provided evaluation script, the assignment will need to inform the student to upload their _makefile_ with their submission. 
    c. Once the files are selected, the student clicks OK to start the evaluation. 
             i. The extension makes a `POST` request to our backend API server with the uploaded files as a parameter of the type multipart/form-data. 
             ii. An API is invoked that will compile their assignment using the evaluation script provided by the instructor or student. 
             iii. A success Boolean (pass/fail) is returned along with the compiler output if there is a compilation error.
                              1. Upon successful evaluation, the student is shown a success message that the files are ready for submission on Canvas. The evaluate does not submit the files on behalf of the students.  
                              2. If the evaluation fails, a small portion of the error message is displayed to the student, which they can use to correct errors in the submission and try again. 
   

4. After successful submission, the instructor/grader can grade the submission from within the Canvas via the Chrome extension:

    a. The instructor opens the Canvas SpeedGrader for the assignment to grade the student’s submission. 
    b. Upon page load, an API is invoked on the backend server to fetch the student’s submission files and the evaluation script associated with the assignment.  
            i. The backend writes the files to a submission directory and return a response to the extension that contains the names of the files, their contents (code), and the name of the submission directory. 
    c. The extension renders the read-only view of the code and a terminal window by parsing the API response. 
            i. The read-only view of the code will be built using the code and names of each file from the API response. 
            ii. In the terminal window, the extension automatically connects to the SU-hosted Linux environment via SSH and navigates to the submission directory. 
    d. The instructor can click through each submission file using the tab of the read-only view to examine the contents. 
    e. The instructor will either navigate to the terminal interface, located below the read-only view of the student’s code, or press the build button, to execute the code. 
            i. Button:  
                    1. First the grader clicks on the build button. The code will be automatically compiled. The terminal view will display the commands ran to compile the submission.  
                    2. The executable file will be displayed in highlighted font in the open directory created, leaving the following commands on the terminal: “./”.   
                    3. The instructor will then need to input the name of the executable file in command line, `./<NameOfExecutable>` and hit enter. This will establish the SSH connection and the grader can interact with the program during run time. 
                    4. To terminate the program, the grader will click on the stop button. 
            ii. Terminal:  
                    1. First, the grader will compile the code using the makefile, which will produce the executable file. 
                    2. Then, the grader will run the executable file. 
                    3. With full SSH access, the grader is free to interact with and terminate the program, if necessary. 
    f. After assessing a student’s submission, the instructor will open the student drop down menu in the Canvas UI, select the next student submission to assess and repeat steps 4b-4e. 
   

System Architecture

High Level Overview

Chrome Extension

• Connects directly to the SeattleU Hosted server via SSH
• Makes API calls to the Spring Boot App
• Compile/execute code on the SeattleU Hosted Server through the embedded terminal

Spring Boot App

• Runs in the SeattleU Hosted Server
• Makes external Canvas API calls via REST
• Create submission directory locally on the SeattleU Hosted Server

Figure 5. Canvas Code Extension Architecture

Frontend

The elements created are sectioned into two parts; Student View elements and Instructor view elements. All elements are JS objects injected into the D.O.M. of the canvas webpages. The DOM is an object that represents the structure of a webpage. The document object has elements (other objects) and methods just like any other JavaScript object. Referencing these methods and objects within a document allow for reading and writing to the DOM which in turn will modify the browser’s representation of a webpage. Using Reacts framework and integration with webpack, we can package the frontend components to render on Canvas’ pages using static references of our code.

DOM can be visualized as a tree of elements/objects that exist within our webpage. Elements created for the student and instructor view are JS objects that are injected into the existing DOM tree hierarchy.

Figure 6. DOM Architecture

There are 4 main components to create the chrome extension.

1. Manifest.json file

2. Content scripts

3. Background Scripts

4. Popup page(s)

Manifest.json

Is the skeleton of our extension. It contains basic information such as the title, description, and manifest version being used. Additionally, the manifest guides the browser when to use extension. This includes what pages/urls that extension can actively be used on, permissions alloted, and the files/scripts that can be used.

Content Scripts

A content script is a script that runs in a specific context in a webpage. The context is set within the Manifest.json, based on the accepted URLs. Content scripts have access to the DOM tree allowing for reading and manipulation of the DOM and therefore webpage.

The content script allowed us dynamically create DOM elements like buttons that were injected within the webpage. Our custom DOM elements were given event listeners that could then contact our backend to send files and receive a response. The response could then be handled and further information could then be routed to the background script.

Background Scripts (Service Worker)

Background scripts are a part of the browser. They help perform actions that don’t directly access the DOM/webpage. Instead, the integration with the browser allows the background script to listen for events such as new tabs being opened, button clicks, or even open new tabs/windows.

For our project we leveraged the background scripts to receive messages from the content scripts and open new pages with the results of a student submission.

Popup Pages

Popup pages are additional HMTL/JS elements that are optional to in a chrome extension. For our project we had a extension popup and a submission results popup. The extension popup briefly explained the application and was the entry point for our user authentication. The submission popup provided the user with feedback about their assignment submissions.

Student View - Code Submission Validation

Figure 7. Student View Frontend

1. Content script is loaded by the manifest.json
2. Content is given access to the D.O.M.
3. Student content script creates a script element (inject script)
4. Inject script is injected into the D.O.M. along with its child objects and methods (I.e. injected button).
5. A click event is detected, and file(s) are sent from the DOM back to the inject script.
6. The inject script formats the files and sends them in a POST request to the backend server and receives the server’s response.
7. The inject script sends the server response back upstream to the content script to be processed.
8. The content script sends the proper message type and data to the background script and receives an acknowledgement.
9. The background script uses the Chrome API to generates a new window that displays the results or any errors that occurred during the process.

Instructor View - Read-Only Code View & SSH Terminal

Figure 8. Instructor View Frontend

1. Content script is loaded by the manifest.json
2. Content is given access to the D.O.M.
3. Instructor content script creates a script element (inject script)
4. Inject script is injected into the D.O.M. along with its child objects and methods (I.e. Read-only view and ssh terminal).
5. A URL changes event is detected, and file(s) are loaded from the backend to the inject script.
6. The inject script retrieves the student submission files and validation script with a GET request to the backend server and receives the server’s response.
7. The inject script sends the server response back upstream to the content script to be processed.
8. The content script sends the proper message type and data to the background script and receives an acknowledgement.
9. The background script uses the Chrome API to generate a new window that displays the submission file data and ssh terminal connection.

Backend

Student View – Validation Script and Code Compilation

We are simplifying the student submission process by allowing students to upload their files on Canvas and receive a validation check to ensure their code compiles before submitting their assignment. Instructors will no longer be required to create a validation script, typically written in Perl, for CS1, as our solution only requires the makefile for .cpp code files, either provided by the instructor or the student. Our system manages handling the files for executing the validation check.

Figure 9. Canvas Code Student Sequence Workflow

Instructor View – Read-Only Code View and SSH Terminal

We are providing a read-only view of the student code submission files and a terminal window where the instructor can execute the student submission files within the Canvas SpeedGrader UI.

Diagram 10 shows the sequence of events and interactions between each component of the SSH solution, including the external API call to Canvas.

Figure 10. SSH Full Sequence Workflow

Below, the diagrams 11-14 are sections of Figure 6, separated for readability.

Figure 11. Creating the Read-Only View

Figure 12. Connect to Terminal Submission Direction in SSH Server

Figure 13. Instructor Executes Code and Grades Assignment

Figure 14. Instructor Exits SpeedGrader or Switches Students

Execute Code using Terminal Commands

The instructor has full access to the SU-hosted server, via the SSH terminal. They handle executing the makefile to build the code and create the executable.

Figure 14. Execute Code via Terminal

Execute Code using Build Button

Pressing the build button should automatically input commands into the terminal

Figure 15. Execute Code via Extension Build Button